components/x11/xorg-docs/src/input/XKB-Enhancing.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>How to further enhance XKB configuration</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_9276" /><meta name="description" content="This guide is aimed to relieve one's labour to create a new (internationalized) keyboard layout. Unlike other documents this guide accents the keymap developer's point of view." /><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-Enhancing"></a>How to further enhance XKB configuration</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">25 November 2002</p></div><div><div class="abstract"><p>
 307 This guide is aimed to relieve one's labour to create a new (internationalized)
 308 keyboard layout. Unlike other documents this guide accents the keymap developer's point of view.
 309       </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="#The_Basics">The Basics</a></span></dt><dt><span class="sect1"><a href="#Enhancing_XKB_Configuration">Enhancing XKB Configuration</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Levels_And_Groups">Levels And Groups</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Defining_New_Layouts">Defining New Layouts</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Predefined_XKB_Symbol_Sets">Predefined XKB Symbol Sets</a></span></dt><dt><span class="sect2"><a href="#Key_Types">Key Types</a></span></dt><dt><span class="sect2"><a href="#Rules">Rules</a></span></dt><dt><span class="sect2"><a href="#Descriptive_Files_of_Rules">Descriptive Files of Rules</a></span></dt></dl></dd></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>
 310 The developer of a new layout should read the xkb
 311 protocol specification (<a class="ulink" href="http://www.x.org/docs/XKB/XKBproto.pdf" target="_top">The X Keyboard Extension: Protocol Specification</a>) at least
 312 to clarify for himself some xkb-specific terms used in this document
 313 and elsewhere in xkb configuration. Also it shows wise to understand
 314 how the X server and a client digest their keyboard inputs
 315 (with and without xkb).
 316     </p><p>
 317 A useful source is also <a class="ulink" href="http://www.tsu.ru/~pascal/en/xkb" target="_top">Ivan  Pascal's text about xkb configuration</a> often referenced throughout this
 318 document.
 319     </p><p>
 320 Note that this document covers only enhancements which
 321 are to be made to XFree86 version 4.3 and X11R6.7.0 and above.
 322     </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="The_Basics"></a>The Basics</h2></div></div></div><p>
 323 At the startup (or at later at user's command) X server starts its xkb
 324 keyboard module extension and reads data from a compiled configuration
 325 file.
 326     </p><p>
 327 This compiled configuration file is prepared by the
 328 program <span class="command"><strong>xkbcomp</strong></span> which behaves altogether as an
 329 ordinary compiler (see <strong class="userinput"><code>man xkbcomp</code></strong>).
 330 Its input are human readable xkb configuration files which are verified and
 331 then composed into a useful xkb configuration. Users don't need to mess with
 332 <span class="command"><strong>xkbcomp</strong></span> themselves, for them it is invisible. Usually,
 333 it is started upon X server startup.
 334     </p><p>
 335 As you probably already know, the xkb configuration consists of five
 336 main modules:
 337       </p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /></colgroup><tbody><tr><td><p><span class="term">Keycodes</span></p></td><td><p>
 338 Tables that defines translation from keyboard scan codes into reasonable
 339 symbolic names, maximum, minimum legal keycodes, symbolic aliases and
 340 description of physically present LED-indicators. The primary sence of
 341 this component is to allow definitions of maps of symbols (see below)
 342 to be independent of physical keyboard scancodes. There are two main
 343 naming conventions for symbolic names (always four bytes long):
 344
 345               </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
 346  names which express some traditional meaning like
 347 <span class="keycode">&lt;SPCE&gt;</span> (stands for space bar) or
 348                   </p></li><li class="listitem"><p>
 349  names which express some relative positioning on a keyboard, for
 350 example <span class="keycode">&lt;AE01&gt;</span> (an exclamation mark on US keyboards), on
 351 the right there are keys <span class="keycode">&lt;AE02&gt;</span>, <span class="keycode">&lt;AE03&gt;</span>
 352 etc.
 353                   </p></li></ul></div><p>
 354
 355             </p></td></tr><tr><td><p><span class="term">Types</span></p></td><td><p>
 356 Types describe how the produced key is changed by active modifiers (like
 357 Shift, Control, Alt, ...). There are several predefined types which
 358 cover most of used combinations.
 359             </p></td></tr><tr><td><p><span class="term">Compat</span></p></td><td><p>
 360 Compatibility component defines internal behaviour of modifiers. Using
 361 compat component you can assign various actions (elaborately described
 362 in xkb specification) to key events. This is also the place where
 363 LED-indicators behaviour is defined.
 364             </p></td></tr><tr><td><p><span class="term">Symbols</span></p></td><td><p>
 365 For i18n purposes, this is the most important table. It defines what
 366 values (=symbols) are assigned to what keycodes (represented by their
 367 symbolic name, see above). There may be defined more than one value
 368 for each key and then it depends on a key type and on modifiers state
 369 (respective compat component) which value will be the resulting one.
 370             </p></td></tr><tr><td><p><span class="term">Geometry</span></p></td><td><p>
 371 Geometry files aren't used by xkb itself but they may be used by some
 372 external programs to depict a keyboard image.
 373             </p></td></tr></tbody></table></div><p>
 374 All these components have the files located in xkb configuration tree
 375 in subdirectories with the same names (usually in
 376 <code class="filename">/usr/lib/X11/xkb</code>).
 377     </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Enhancing_XKB_Configuration"></a>Enhancing XKB Configuration</h2></div></div></div><p>
 378 Most of xkb enhancements concerns a need to define new output symbols
 379 for the some input key events. In other words, a need to define a new
 380 symbol map (for a new language, standard or just to feel more comfortable
 381 when typing text).
 382     </p><p>
 383 What do you need to do? Generally, you have to define following things:
 384
 385       </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
 386  the map of symbols itself
 387           </p></li><li class="listitem"><p>
 388  the rules to allow users to select the new mapping
 389           </p></li><li class="listitem"><p>
 390  the description of the new layout
 391           </p></li></ul></div><p>
 392
 393     </p><p>
 394 First of all, it is good to go through existing layouts and to examine
 395 them if there is something you could easily adjust to fit your needs.
 396 Even if there is nothing similar you may get some ideas about basic
 397 concepts and used tricks.
 398     </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Levels_And_Groups"></a>Levels And Groups</h3></div></div></div><p>
 399 Since XFree86 4.3.0 and X11R6.7.0 you can use
 400 <em class="firstterm">multi-layout</em> concept of xkb
 401 configuration.
 402 Though it is still in boundaries of xkb protocol and general ideas, the
 403 keymap designer must obey new rules when creating new maps. In exchange
 404 we get a more powerful and cleaner configuration system.
 405       </p><p>
 406 Remember that it is the application which must decide which symbol
 407 matches which keycode according to effective modifier state. The X server
 408 itself sends only an input event message to. Of course, usually
 409 the general interpretation is processed by Xlib, Xaw, Motif, Qt, Gtk
 410 and similar libraries. The X server only supplies its mapping table
 411 (usually upon an application startup).
 412       </p><p>
 413 You can think of the X server's symbol table as of a irregular table where each
 414 keycode has its row and where each combination of modifiers determines exactly
 415 one column. The resulting cell then gives the proper symbolic value. Not all
 416 keycodes need to bind different values for different combination of modifiers.
 417 <span class="keycode">&lt;ENTER&gt;</span> key, for instance, usually doesn't depend on any
 418 modifiers so it its row has only one column defined.
 419       </p><p>
 420 Note that in XKB there is no prior assumption that certain modifiers are bound
 421 to certain columns. By editing proper files (see <a class="xref" href="#Key_Types" title="Key Types">Key Types</a>)
 422 this mapping can be changed as well.
 423       </p><p>
 424 Unlike the original X protocol the XKB approach is far more
 425 flexible. It is comfortable to add one additional XKB term - group. You can
 426 think of a group as of a vector of columns per each keycode (naturally the
 427 dimension of this vector may differ for different keycodes). What is it good
 428 for? The group is not very useful unless you intend to use more than one
 429 logically different set of symbols (like more than one alphabet) defined in a
 430 single mapping table. But then, the group has a natural meaning - each symbol
 431 set has its own group and changing it means selecting a different one.
 432 XKB approach allows up to four different groups. The columns inside each group
 433 are called (shift) levels. The X server knows the current group and reports it
 434 together with modifier set and with a keycode in key events.
 435       </p><p>
 436 To sum it up:
 437
 438         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
 439  for each keycode XKB keyboard map contains up to four one-dimensional
 440 tables - groups (logically different symbol sets)
 441             </p></li><li class="listitem"><p>
 442  for each group of a keycode XKB keyboard map contains some columns
 443 - shift levels (values reached by combinations of Shift, Ctrl, Alt, ...
 444 modifiers)
 445             </p></li><li class="listitem"><p>
 446  different keycodes can have different number of groups
 447             </p></li><li class="listitem"><p>
 448  different groups of one keycode can have different number of shift levels
 449             </p></li><li class="listitem"><p>
 450  the current group number is tracked by X server
 451             </p></li></ul></div><p>
 452       </p><p>
 453 It is clear that if you sanely define levels, groups and sanely bind
 454 modifiers and associated actions you can have simultaneously loaded up to
 455 four different symbol sets where each of them would reside in its own group.
 456       </p><p>
 457 The multi-layout concept provides a facility to manipulate xkb groups
 458 and symbol definitions in a way that allows almost arbitrary composition of
 459 predefined symbol tables. To keep it fully functional you have to:
 460
 461         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
 462  define all symbols only in the first group
 463             </p></li><li class="listitem"><p>
 464  (re)define any modifiers with extra care to avoid strange (anisometric)
 465 behaviour
 466             </p></li></ul></div><p>
 467
 468       </p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Defining_New_Layouts"></a>Defining New Layouts</h2></div></div></div><p>
 469 See <a class="ulink" href="http://www.tsu.ru/~pascal/en/xkb/internals.html" target="_top">Some Words  About XKB internals</a> for explanation of used xkb terms and problems
 470 addressed by XKB extension.
 471     </p><p>
 472 See <a class="ulink" href="http://www.tsu.ru/~pascal/en/xkb/gram-common.html" target="_top">Common  notes about XKB configuration files language</a> for more precise explanation of
 473 syntax of xkb configuration files.
 474     </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Predefined_XKB_Symbol_Sets"></a>Predefined XKB Symbol Sets</h3></div></div></div><p>
 475 If you are about to define some European symbol map extension, you might
 476 want to use on of four predefined latin alphabet layouts.
 477       </p><p>
 478 Okay, let's assume you want extend an existing keymap and you want to override
 479 a few keys. Let's take a simple U.K. keyboard as an example (defined in
 480 <code class="filename">pc/gb</code>):
 481
 482         </p><pre class="screen">
 483 partial default alphanumeric_keys
 484 xkb_symbols "basic" {
 485   include "pc/latin"
 486
 487   name[Group1]="Great Britain";
 488
 489   key &lt;AE02&gt;  { [         2,   quotedbl,  twosuperior,    oneeighth ] };
 490   key &lt;AE03&gt;  { [         3,   sterling, threesuperior,    sterling ] };
 491   key &lt;AC11&gt;  { [apostrophe,         at, dead_circumflex, dead_caron] };
 492   key &lt;TLDE&gt;  { [     grave,    notsign,          bar,          bar ] };
 493   key &lt;BKSL&gt;  { [numbersign, asciitilde,   dead_grave,   dead_breve ] };
 494   key &lt;RALT&gt;  { type[Group1]="TWO_LEVEL",
 495                 [ ISO_Level3_Shift, Multi_key ]   };
 496
 497   modifier_map Mod5   { &lt;RALT&gt; };
 498 };
 499         </pre><p>
 500
 501       </p><p>
 502 It defines a new layout in <code class="literal">basic</code> variant as an extension of common
 503 latin alphabet layout. The layout (symbol set) name is set to "Great Britain".
 504 Then there are redefinitions of a few keycodes and a modifiers binding. As you
 505 can see the number of shift levels is the same for
 506 <span class="keycode">&lt;AE02&gt;</span>, <span class="keycode">&lt;AE03&gt;</span>,
 507 <span class="keycode">&lt;AC11&gt;</span>, <span class="keycode">&lt;TLDE&gt;</span> and
 508 <span class="keycode">&lt;BKSL&gt;</span> keys but it differs from number of shift
 509 levels of <span class="keycode">&lt;RALT&gt;</span>.
 510       </p><p>
 511 Note that the <span class="keycode">&lt;RALT&gt;</span> key itself is a binding key for Mod5 and
 512 that it
 513 serves like a shift modifier for LevelThree, together with Shift
 514 as a multi-key. It is a good habit to respect this rule in a new similar
 515 layout.
 516       </p><p>
 517 Okay, you could now define more variants of your new layout besides
 518 <code class="literal">basic</code> simply by including (augmenting/overriding/...) the basic
 519 definition and altering what may be needed.
 520       </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Key_Types"></a>Key Types</h3></div></div></div><p>
 521 The differences in the number of columns (shift levels) are caused by
 522 a different types of keys (see the types definition in section basics).  Most
 523 keycodes have implicitly set the keytype in the included
 524 <span class="quote">“<span class="quote"><code class="filename">pc/latin</code></span>”</span> file to
 525 <span class="quote">“<span class="quote"><code class="literal">FOUR_LEVEL_ALPHABETIC</code></span>”</span>. The only exception is
 526 <span class="keycode">&lt;RALT&gt;</span> keycode which is explicitly set
 527 <span class="quote">“<span class="quote"><code class="literal">TWO_LEVEL</code></span>”</span> keytype.
 528       </p><p>
 529 All those names refer to pre-defined shift level schemes. Usually you can
 530 choose a suitable shift level scheme from <code class="literal">default</code> types scheme list
 531 in proper xkb component's subdirectory.
 532       </p><p>
 533 The most used schemes are:
 534         </p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /></colgroup><tbody><tr><td><p><span class="term">ONE_LEVEL</span></p></td><td><p>
 535 The key does not depend on any modifiers. The symbol from first level
 536 is always chosen.
 537               </p></td></tr><tr><td><p><span class="term">TWO_LEVEL</span></p></td><td><p>
 538 The key uses a modifier Shift and may have two possible values.
 539 The second level may be chosen by Shift modifier. If Lock modifier
 540 (usually Caps-lock) applies the symbol is further processed using
 541 system-specific capitalization rules. If both Shift+Lock modifier apply the
 542 symbol from the second level is taken and capitalization rules are applied
 543 (and usually have no effect).
 544               </p></td></tr><tr><td><p><span class="term">ALPHABETIC</span></p></td><td><p>
 545 The key uses modifiers Shift and Lock. It may have two possible
 546 values. The second level may be chosen by Shift modifier. When Lock
 547 modifier applies, the symbol from the first level is taken and further
 548 processed using system-specific capitalization rules. If both Shift+Lock
 549 modifier apply the symbol from the first level is taken and no
 550 capitalization rules applied. This is often called shift-cancels-caps
 551 behaviour.
 552               </p></td></tr><tr><td><p><span class="term">THREE_LEVEL</span></p></td><td><p>
 553 Is the same as TWO_LEVEL but it considers an extra modifier -
 554 LevelThree which can be used to gain the symbol value from the third
 555 level. If both Shift+LevelThree modifiers apply the value from the third
 556 level is also taken. As in TWO_LEVEL, the Lock modifier doesn't influence
 557 the resulting level. Only Shift and LevelThree are taken into that
 558 consideration. If the Lock modifier is active capitalization rules
 559 are applied on the resulting symbol.
 560               </p></td></tr><tr><td><p><span class="term">FOUR_LEVEL</span></p></td><td><p>
 561 Is the same as THREE_LEVEL but unlike LEVEL_THREE if both Shift+LevelThree
 562 modifiers apply the symbol is taken from the fourth level.
 563               </p></td></tr><tr><td><p><span class="term">FOUR_LEVEL_ALPHABETIC</span></p></td><td><p>
 564 Is similar to FOUR_LEVEL but also defines shift-cancels-caps behaviour
 565 as in ALPHABETIC. If Lock+LevelThree apply the symbol from the
 566 third level is taken and the capitalization rules are applied.
 567 If Lock+Shift+LevelThree apply the symbol from the third level is taken
 568 and no capitalization rules are applied.
 569               </p></td></tr><tr><td><p><span class="term">KEYPAD</span></p></td><td><p>
 570 As the name suggest this scheme is primarily used for numeric keypads.
 571 The scheme considers two modifiers - Shift and NumLock. If none
 572 of modifiers applies the symbol from the first level is taken. If either
 573 Shift or NumLock modifiers apply the symbol from the second level is taken.
 574 If both Shift+NumLock modifiers apply the symbol from the first level
 575 is taken. Again, shift-cancels-caps variant.
 576               </p></td></tr><tr><td><p><span class="term">FOUR_LEVEL_KEYPAD</span></p></td><td><p>
 577 Is similar to KEYPAD scheme but considers also LevelThree modifier.
 578 If LevelThree modifier applies the symbol from the third level is taken.
 579 If Shift+LevelThree or NumLock+LevelThree apply the symbol from the fourth
 580 level is taken. If all Shift+NumLock+LevelThree modifiers apply the symbol
 581 from the third level is taken. This also, shift-cancels-caps variant.
 582               </p></td></tr></tbody></table></div><p>
 583       </p><p>
 584 Besides that, there are several schemes for special purposes:
 585         </p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /></colgroup><tbody><tr><td><p><span class="term">PC_BREAK</span></p></td><td><p>
 586 It is similar to TWO_LEVEL scheme but it considers the Control
 587 modifier rather than Shift. That means, the symbol from the second level
 588 is chosen by Control rather than by Shift.
 589               </p></td></tr><tr><td><p><span class="term">PC_SYSRQ</span></p></td><td><p>
 590 It is similar to TWO_LEVEL scheme but it considers the Alt modifier rather
 591 than Shift. That means, the symbol from the second level
 592 is chosen by Alt rather than by Shift.
 593               </p></td></tr><tr><td><p><span class="term">CTRL+ALT</span></p></td><td><p>
 594 The key uses modifiers Alt and Control. It may have two possible
 595 values. If only one modifier (Alt or Control) applies the symbol
 596 from the first level is chosen. Only if both Alt+Control modifiers apply
 597 the symbol from the second level is chosen.
 598               </p></td></tr><tr><td><p><span class="term">SHIFT+ALT</span></p></td><td><p>
 599 The key uses modifiers Shift and Alt. It may have two possible values.
 600 If only one modifier (Alt or Shift) applies the symbol
 601 from the first level is chosen. Only if both Alt+Shift modifiers apply
 602 the symbol from the second level is chosen.
 603               </p></td></tr></tbody></table></div><p>
 604       </p><p>
 605 If needed, special <code class="literal">caps</code> schemes may be used.
 606 They redefine the standard behaviour of all
 607 <code class="literal">*ALPHABETIC</code> types. The layouts (maps of
 608 symbols) with keys defined in respective types then automatically change
 609 their behaviour accordingly. Possible redefinitions are:
 610
 611         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>internal</p></li><li class="listitem"><p>internal_nocancel</p></li><li class="listitem"><p>shift</p></li><li class="listitem"><p>shift_nocancel</p></li></ul></div><p>
 612
 613 None of these schemes should be used directly. They are defined merely
 614 for <code class="literal">'caps:'</code> xkb options (used to globally
 615 change the layouts behaviour).
 616       </p><p>
 617 Don't alter any of existing key types. If you need a different behaviour
 618 create a new one.
 619       </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="More_On_Definitions_Of_Types"></a>More On Definitions Of Types</h4></div></div></div><p>
 620 When the XKB software deals with a separate type description it gets
 621 a complete list of modifiers that should be taken into account from the
 622 <code class="literal">'modifiers=&lt;list of modifiers&gt;'</code> list and expects that a set
 623 of <code class="literal">'map[&lt;combination of modifiers&gt;]=&lt;list of modifiers&gt;'</code>
 624 instructions that contain the mapping for each combination of modifiers
 625 mentioned in that list. Modifiers that are not explicitly listed are NOT taken
 626 into account
 627 when the resulting shift level is computed.
 628 If some combination is omitted the program (subroutine) should choose the first
 629 level for this combination (a quite reasonable behavior).
 630         </p><p>
 631 Lets consider an example with two modifiers <span class="keysym">ModOne</span> and
 632 <span class="keysym">ModTwo</span>:
 633
 634           </p><pre class="screen">
 635 type "..." {
 636     modifiers = ModOne+ModTwo;
 637     map[None] = Level1;
 638     map[ModOne] = Level2;
 639 };
 640           </pre><p>
 641
 642 In this case the map statements for <span class="keysym">ModTwo</span> only and
 643 <span class="keysym">ModOne+ModTwo</span> are omitted.  It means that if
 644 the <span class="keysym">ModTwo</span> is active the subroutine can't found
 645 explicit mapping for such combination an will use
 646 the <span class="emphasis"><em>default level</em></span> i.e. Level1.
 647         </p><p>
 648 But in the case the type described as:
 649
 650           </p><pre class="screen">
 651 type "..." {
 652     modifiers = ModOne;
 653     map[None] = Level1;
 654     map[ModOne] = Level2;
 655 };
 656           </pre><p>
 657
 658 the ModTwo will not be taken into account and the resulting level depends on
 659 the ModOne state only. That means, ModTwo alone produces the Level1 but the
 660 combination ModOne+ModTwo produces the Level2 as well as ModOne alone.
 661         </p><p>
 662 What does it mean if the second modifier is the Lock? It means that in
 663 the first case (the Lock itself is included in the list of modifiers but
 664 combinations with this modifier aren't mentioned in the map statements)
 665 the internal capitalization rules will be applied to the symbol from the first
 666 level. But in the second case the capitalization will be applied to the symbol
 667 chosen accordingly to he first modifier - and this can be the symbol from the
 668 first as well as from the second level.
 669         </p><p>
 670 Usually, all modifiers introduced in <code class="literal">'modifiers=&lt;list of modifiers&gt;'</code> list are used for shift level calculation and then
 671 discarded. Sometimes this is not desirable. If you want to use a modifier
 672 for shift level calculation but you don't want to discard it, you may
 673 list in '<code class="literal">preserve[&lt;combination of modifiers&gt;]=&lt;list of modifiers&gt;'</code>. That means, for a given combination all listed modifiers
 674 will be preserved. If the Lock modifier is preserved then the resulting
 675 symbol is passed to internal capitalization routine regardless whether
 676 it has been used for a shift level calculation or not.
 677         </p><p>
 678 Any key type description can use both real and virtual modifiers. Since real
 679 modifiers always have standard names it is not necessary to explicitly declare
 680 them. Virtual modifiers can have arbitrary names and can be declared (prior
 681 using them) directly in key type definition:
 682
 683           </p><pre class="screen">
 684 virtual_modifiers &lt;comma-separated list of modifiers&gt;  ;
 685           </pre><p>
 686
 687 as seen in for example <code class="literal">basic</code>, <code class="literal">pc</code> or <code class="literal">mousekeys</code> key
 688 type definitions.
 689         </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Rules"></a>Rules</h3></div></div></div><p>
 690 Once you are finished with your symbol map you need to add it
 691 to rules file. The rules file describes how all the
 692 five basic keycodes, types, compat, symbols and geometry components
 693 should be composed to give a sensible resulting xkb configuration.
 694       </p><p>
 695 The main advantage of rules over formerly used keymaps is a possibility
 696 to simply parameterize (once) fixed patterns of configurations and thus
 697 to elegantly allow substitutions of various local configurations
 698 into predefined templates.
 699       </p><p>
 700 A pattern in a rules file (often located in
 701 <code class="filename">/usr/lib/X11/xkb/rules</code>)
 702  can be parameterized with four other arguments:
 703 <code class="literal">Model</code>, <code class="literal">Layout</code>,
 704 <code class="literal">Variant</code> and <code class="literal">Options</code>.
 705 For most cases parameters <code class="literal">model</code> and
 706 <code class="literal">layout</code> should
 707 be sufficient for choosing a functional keyboard mapping.
 708       </p><p>
 709 The rules file itself is composed of pattern lines and lines with rules. The
 710 pattern line starts with an exclamation mark ('<code class="literal">!</code>')
 711 and describes how will the xkb interpret the following lines (rules). A sample
 712 rules file looks like this:
 713
 714         </p><pre class="screen">
 715 ! model                         =       keycodes
 716   macintosh_old                 =       macintosh
 717   ...
 718   *                             =       xorg
 719
 720 ! model                         =       symbols
 721   hp                            =       +inet(%m)
 722   microsoftpro                  =       +inet(%m)
 723   geniuscomfy                   =       +inet(%m)
 724
 725 ! model     layout[1]           =       symbols
 726   macintosh     us              =       macintosh/us%(v[1])
 727   *             *               =       pc/pc(%m)+pc/%l[1]%(v[1])
 728
 729 ! model     layout[2]           =       symbols
 730   macintosh     us              =       +macintosh/us[2]%(v[2]):2
 731   *             *               =       +pc/%l[2]%(v[2]):2
 732
 733 ! option                        =       types
 734   caps:internal                 =       +caps(internal)
 735   caps:internal_nocancel        =       +caps(internal_nocancel)
 736         </pre><p>
 737
 738       </p><p>
 739 Each rule defines what certain combination of values on the left side
 740 of equal sign ('<code class="literal">=</code>') results in. For
 741 example a (keyboard) model <code class="literal">macintosh_old</code>
 742 instructs xkb to take definitions of keycodes from
 743 file <code class="filename">keycodes/macintosh</code> while the rest
 744 of models (represented by a wild card '<code class="literal">*</code>')
 745 instructs it to take them from file <code class="filename">keycodes/xorg</code>.
 746 The wild card represents all possible values on the left side which
 747 were not found in any of the previous rules.  The more specialized
 748 (more complete) rules have higher precedence than general ones,
 749 i.e. the more general rules supply reasonable default values.
 750       </p><p>
 751 As you can see some lines contain substitution parameters - the parameters
 752 preceded by the percent sign ('<code class="literal">%</code>').
 753 The first alphabetical character after the percent sign expands to the
 754 value which has been found on the left side. For
 755 example <code class="literal">+%l%(v)</code> expands
 756 into <code class="literal">+cz(bksl)</code> if the respective values
 757 on the left side were <code class="literal">cz</code> layout in
 758 its <code class="literal">bksl</code> variant. More, if the layout
 759 resp. variant parameter is followed by a pair of brackets
 760 ('<code class="literal">[</code>', '<code class="literal">]</code>')
 761 it means that xkb should <span class="emphasis"><em>place the layout resp. variant into
 762 specified xkb group</em></span>. If the brackets are omitted the first
 763 group is the default value.
 764       </p><p>
 765 So the second block of rules enhances symbol definitions for some particular
 766 keyboard models with extra keys (for internet, multimedia, ...) . Other models
 767 are left intact. Similarly, the last block overrides some key type definitions,
 768 so the common global behaviour ''shift cancels caps'' or ''shift doesn't cancel
 769 caps'' can be selected. The rest of rules produces special symbols for each
 770 variant <code class="literal">us</code> layout of
 771 <code class="literal">macintosh</code> keyboard and standard pc
 772 symbols in appropriate variants as a default.
 773       </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Descriptive_Files_of_Rules"></a>Descriptive Files of Rules</h3></div></div></div><p>
 774 Now you just need to add a detailed description to
 775 <code class="filename">&lt;rules&gt;.xml</code>
 776 description file so the other users (and external programs which often parse
 777 this file) know what is your work about.
 778       </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Old_Descriptive_Files"></a>Old Descriptive Files</h4></div></div></div><p>
 779 The formerly used descriptive files were named <code class="filename">&lt;rules&gt;.lst</code>
 780 Its structure is very simple and quite self descriptive but such simplicity
 781 had also some cavities, for example there was no way how to describe local
 782 variants of layouts and there were problems with the localization of
 783 descriptions. To preserve compatibility with some older programs,
 784 new XML descriptive files can be converted to old format '.lst'.
 785         </p><p>
 786 For each parameter of rules file should be described its meaning. For the rules
 787 file described above the <code class="filename">.lst</code> file could look like:
 788
 789           </p><pre class="screen">
 790 ! model
 791   pc104         Generic 104-key PC
 792   microsoft     Microsoft Natural
 793   pc98          PC-98xx Series
 794   macintosh     Original Macintosh
 795   ...
 796
 797 ! layout
 798   us            U.S. English
 799   cz            Czech
 800   de            German
 801   ...
 802
 803 ! option
 804   caps:internal          uses internal capitalization. Shift cancels Caps
 805   caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
 806
 807           </pre><p>
 808
 809         </p><p>
 810 And that should be it. Enjoy creating your own xkb mapping.
 811         </p></div></div></div></div></body></html>