1056N/A<?
xml version="1.0" encoding="UTF-8"?>
1276N/A<
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">/*
1276N/A * Copyright (c) 2011 Gaetan Nadon
1276N/A * Copyright (c) 2010, Oracle
and/
or its affiliates. All rights reserved.
1276N/A * Permission is hereby granted, free of charge, to any person obtaining a
1276N/A * copy of this software and associated documentation files (the "Software"),
1276N/A * to deal in the Software without restriction, including without limitation
1276N/A * the rights to use, copy, modify, merge, publish, distribute, sublicense,
1276N/A *
and/
or sell copies of the Software, and to permit persons to whom the
1276N/A * Software is furnished to do so, subject to the following conditions:
1276N/A * The above copyright notice and this permission notice (including the next
1276N/A * paragraph) shall be included in all copies or substantial portions of the
1276N/A * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1276N/A * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1276N/A * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
1276N/A * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1276N/A * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
1276N/A * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
1276N/A * DEALINGS IN THE SOFTWARE.
1276N/A * Shared stylesheet for
X.Org documentation translated to HTML format
1276N/A * The sans-serif fonts are considered more legible on a computer screen
1276N/A font-family: "Bitstream Vera Sans", "DejaVu Sans", Tahoma, Geneva, Arial, Sans-serif;
1276N/A /* In support of using "em" font size unit, the w3c recommended method */
1276N/A * Selection: all elements requiring mono spaced fonts.
1276N/A * The family names attempt to match the proportionally spaced font
1276N/A * family names such that the same font name is used for both.
1276N/A * We'd like to use Bitstream, for example, in both proportionally and
1276N/A font-family: "Bitstream Vera Sans Mono", "DejaVu Sans Mono", Courier, "Liberation Mono", Monospace;
1276N/A * Books have a title page, a preface, some chapters and appendices,
1276N/A * a glossary, an index and a bibliography, in that order.
1276N/A * An Article has no preface and no chapters. It has sections, appendices,
1276N/A * a glossary, an index and a bibliography.
1276N/A * Selection: book main title and subtitle
1276N/A * Selection: article main title and subtitle
1276N/A * Selection: various types of authors and collaborators, individuals or corporate
1276N/A * These authors are not always contained inside an authorgroup.
1276N/A * They can be contained inside a lot of different parent types where they might
1276N/A * Reducing the margin at the bottom makes a visual separation between authors
1276N/A * We specify here the ones on the title page, others may be added based on merit.
1276N/A * Selection: the affiliation of various types of authors and collaborators,
1276N/A * individuals or corporate.
1276N/A * Selection: product release information (X Version 11, Release 7)
1276N/A * The releaseinfo element can be contained inside a lot of different parent
1276N/A * types where it might not be centered.
1276N/A * We specify here the one on the title page, others may be added based on merit.
1276N/A * Selection: publishing date
1276N/A * The legal notices are displayed in smaller sized fonts
1276N/A * Justification is only supported in IE and therefore not requested.
1276N/A * For documentation having multiple licenses, the copyright and legalnotice
1276N/A * elements sequence cannot instantiated multiple times.
1276N/A * The copyright notice and license text are therefore coded inside a legalnotice
1276N/A * element. The role attribute on the paragraph is used to allow styling of the
1276N/A * copyright notice text which should not be italicized.
1276N/A * Selection: book or article main ToC title
1276N/A * A paragraph is generated for the title rather than a level 2 heading.
1276N/A * We do not want to select chapters sub table of contents, only the main one
1276N/A * Selection: major sections of a book or an article
1276N/A * Unlike books, articles do not have a titlepage element for appendix.
1276N/A /* Add a border top over the major parts, just like printed books */
1276N/A /* The Gray color is already used for the ruler over the main ToC. */
1276N/A /* Put some space between the border and the title */
1276N/A * A Screen is a verbatim environment for displaying text that the user might
1276N/A * see on a computer terminal. It is often used to display the results of a command.
1276N/A /* Browser's vendor properties prior to CSS 3 */
1276N/A -webkit-border-radius: 1.0em;
1276N/A -khtml-border-radius: 1.0em;
1276N/A * Emphasis program listings with a light shade of gray similar to what
1276N/A * Found many C API docs on the web using like shades of gray.
1276N/A * Emphasis functions synopsis using a darker shade of gray.
1276N/A * Add a border such that it stands out more.
1276N/A * Set the padding so the text does not touch the border.
1276N/A * Selection: paragraphs inside synopsis
1276N/A * Removes the default browser margin, let the container set the padding.
1276N/A * Paragraphs are not always used in synopsis
1276N/A * Selection: variable lists, informal tables and tables
1276N/A * Set the left margin so it is indented to the right
1276N/A * Display informal tables with single line borders
1276N/A * Selection: paragraphs inside tables
1276N/A * Removes the default browser margin, let the container set the padding.
1276N/A * Paragraphs are not always used in tables
1276N/A * Add some space between the left and right column.
1276N/A * The vertical alignment helps the reader associate a term
1276N/A * with a multi-line definition.
1276N/A</
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>
1056N/AThis guide is aimed to relieve one's labour to create a new (internationalized)
1056N/Akeyboard layout. Unlike other documents this guide accents the keymap developer's point of view.
1276N/A </
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>
1056N/AThe developer of a new layout should read the xkb
1056N/Ato clarify for himself some xkb-specific terms used in this document
1056N/Aand elsewhere in xkb configuration. Also it shows wise to understand
1056N/Ahow the X server and a client digest their keyboard inputs
1056N/ANote that this document covers only enhancements which
1056N/Aare to be made to XFree86 version 4.3 and X11R6.7.0 and above.
1276N/A </
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>
1056N/AAt the startup (or at later at user's command) X server starts its xkb
1056N/Akeyboard module extension and reads data from a compiled configuration
1056N/AThis compiled configuration file is prepared by the
1276N/Aprogram <
span class="command"><
strong>xkbcomp</
strong></
span> which behaves altogether as an
1056N/Aordinary compiler (see <
strong class="userinput"><
code>man xkbcomp</
code></
strong>).
1056N/AIts input are human readable xkb configuration files which are verified and
1056N/Athen composed into a useful xkb configuration. Users don't need to mess with
1276N/A<
span class="command"><
strong>xkbcomp</
strong></
span> themselves, for them it is invisible. Usually,
1056N/Ait is started upon X server startup.
1056N/AAs you probably already know, the xkb configuration consists of five
1276N/A </
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>
1056N/ATables that defines translation from keyboard scan codes into reasonable
1056N/Asymbolic names, maximum, minimum legal keycodes, symbolic aliases and
1056N/Adescription of physically present LED-indicators. The primary sence of
1056N/Athis component is to allow definitions of maps of symbols (see below)
1056N/Ato be independent of physical keyboard scancodes. There are two main
1056N/Anaming conventions for symbolic names (always four bytes long):
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A names which express some traditional meaning like
1056N/A<
span class="keycode"><SPCE></
span> (stands for space bar) or
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A names which express some relative positioning on a keyboard, for
1056N/Aexample <
span class="keycode"><AE01></
span> (an exclamation mark on US keyboards), on
1056N/Athe right there are keys <
span class="keycode"><AE02></
span>, <
span class="keycode"><AE03></
span>
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">Types</
span></
p></
td><
td><
p>
1056N/ATypes describe how the produced key is changed by active modifiers (like
1056N/AShift, Control, Alt, ...). There are several predefined types which
1056N/Acover most of used combinations.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">Compat</
span></
p></
td><
td><
p>
1056N/ACompatibility component defines internal behaviour of modifiers. Using
1056N/Acompat component you can assign various actions (elaborately described
1056N/Ain xkb specification) to key events. This is also the place where
1056N/ALED-indicators behaviour is defined.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">Symbols</
span></
p></
td><
td><
p>
1056N/AFor i18n purposes, this is the most important table. It defines what
1056N/Avalues (=symbols) are assigned to what keycodes (represented by their
1056N/Asymbolic name, see above). There may be defined more than one value
1056N/Afor each key and then it depends on a key type and on modifiers state
1056N/A(respective compat component) which value will be the resulting one.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">Geometry</
span></
p></
td><
td><
p>
1056N/AGeometry files aren't used by xkb itself but they may be used by some
1056N/Aexternal programs to depict a keyboard image.
1056N/A </
p></
td></
tr></
tbody></
table></
div><
p>
1056N/AAll these components have the files located in xkb configuration tree
1056N/Ain subdirectories with the same names (usually in
1276N/A </
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>
1056N/AMost of xkb enhancements concerns a need to define new output symbols
1056N/Afor the some input key events. In other words, a need to define a new
1056N/Asymbol map (for a new language, standard or just to feel more comfortable
1056N/AWhat do you need to do? Generally, you have to define following things:
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A the rules to allow users to select the new mapping
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A the description of the new layout
1056N/AFirst of all, it is good to go through existing layouts and to examine
1056N/Athem if there is something you could easily adjust to fit your needs.
1056N/AEven if there is nothing similar you may get some ideas about basic
1276N/A </
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>
1056N/ASince XFree86 4.3.0 and X11R6.7.0 you can use
1056N/A<
em class="firstterm">multi-layout</
em> concept of xkb
1056N/AThough it is still in boundaries of xkb protocol and general ideas, the
1056N/Akeymap designer must obey new rules when creating new maps. In exchange
1056N/Awe get a more powerful and cleaner configuration system.
1056N/ARemember that it is the application which must decide which symbol
1056N/Amatches which keycode according to effective modifier state. The X server
1056N/Aitself sends only an input event message to. Of course, usually
1056N/Athe general interpretation is processed by Xlib, Xaw, Motif, Qt, Gtk
1056N/Aand similar libraries. The X server only supplies its mapping table
1056N/A(usually upon an application startup).
1056N/AYou can think of the X server's symbol table as of a irregular table where each
1056N/Akeycode has its row and where each combination of modifiers determines exactly
1056N/Aone column. The resulting cell then gives the proper symbolic value. Not all
1056N/Akeycodes need to bind different values for different combination of modifiers.
1056N/A<
span class="keycode"><ENTER></
span> key, for instance, usually doesn't depend on any
1056N/Amodifiers so it its row has only one column defined.
1056N/ANote that in XKB there is no prior assumption that certain modifiers are bound
1276N/Ato certain columns. By editing proper files (see <
a class="xref" href="#Key_Types" title="Key Types">Key Types</
a>)
1056N/Athis mapping can be changed as well.
1056N/AUnlike the original X protocol the XKB approach is far more
1056N/Aflexible. It is comfortable to add one additional XKB term - group. You can
1056N/Athink of a group as of a vector of columns per each keycode (naturally the
1056N/Adimension of this vector may differ for different keycodes). What is it good
1056N/Afor? The group is not very useful unless you intend to use more than one
1056N/Alogically different set of symbols (like more than one alphabet) defined in a
1056N/Asingle mapping table. But then, the group has a natural meaning - each symbol
1056N/Aset has its own group and changing it means selecting a different one.
1056N/AXKB approach allows up to four different groups. The columns inside each group
1056N/Aare called (shift) levels. The X server knows the current group and reports it
1056N/Atogether with modifier set and with a keycode in key events.
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A for each keycode XKB keyboard map contains up to four one-dimensional
1056N/Atables - groups (logically different symbol sets)
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A for each group of a keycode XKB keyboard map contains some columns
1056N/A- shift levels (values reached by combinations of Shift, Ctrl, Alt, ...
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A different keycodes can have different number of groups
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A different groups of one keycode can have different number of shift levels
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A the current group number is tracked by X server
1056N/AIt is clear that if you sanely define levels, groups and sanely bind
1056N/Amodifiers and associated actions you can have simultaneously loaded up to
1056N/Afour different symbol sets where each of them would reside in its own group.
1056N/AThe multi-layout concept provides a facility to manipulate xkb groups
1056N/Aand symbol definitions in a way that allows almost arbitrary composition of
1056N/Apredefined symbol tables. To keep it fully functional you have to:
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A define all symbols only in the first group
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A (re)define any modifiers with extra care to avoid strange (anisometric)
1276N/A </
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>
1056N/Asyntax of xkb configuration files.
1276N/A </
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>
1056N/AIf you are about to define some European symbol map extension, you might
1056N/Awant to use on of four predefined latin alphabet layouts.
1056N/AOkay, let's assume you want extend an existing keymap and you want to override
1056N/Aa few keys. Let's take a simple
U.K. keyboard as an example (defined in
1056N/Apartial default alphanumeric_keys
1056N/A name[Group1]="Great Britain";
1056N/A key <AE02> { [ 2, quotedbl, twosuperior, oneeighth ] };
1056N/A key <AE03> { [ 3, sterling, threesuperior, sterling ] };
1056N/A key <AC11> { [apostrophe, at, dead_circumflex, dead_caron] };
1056N/A key <TLDE> { [ grave, notsign, bar, bar ] };
1056N/A key <BKSL> { [numbersign, asciitilde, dead_grave, dead_breve ] };
1056N/A key <RALT> { type[Group1]="TWO_LEVEL",
1056N/A [ ISO_Level3_Shift, Multi_key ] };
1056N/A modifier_map Mod5 { <RALT> };
1056N/AIt defines a new layout in <
code class="literal">basic</
code> variant as an extension of common
1056N/Alatin alphabet layout. The layout (symbol set) name is set to "Great Britain".
1056N/AThen there are redefinitions of a few keycodes and a modifiers binding. As you
1056N/Acan see the number of shift levels is the same for
1056N/A<
span class="keycode"><AE02></
span>, <
span class="keycode"><AE03></
span>,
1056N/A<
span class="keycode"><AC11></
span>, <
span class="keycode"><TLDE></
span> and
1056N/A<
span class="keycode"><BKSL></
span> keys but it differs from number of shift
1056N/Alevels of <
span class="keycode"><RALT></
span>.
1056N/ANote that the <
span class="keycode"><RALT></
span> key itself is a binding key for Mod5 and
1056N/Aserves like a shift modifier for LevelThree, together with Shift
1056N/Aas a multi-key. It is a good habit to respect this rule in a new similar
1056N/AOkay, you could now define more variants of your new layout besides
1056N/Adefinition and altering what may be needed.
1276N/A </
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>
1056N/AThe differences in the number of columns (shift levels) are caused by
1056N/Aa different types of keys (see the types definition in section basics). Most
1056N/Akeycodes have implicitly set the keytype in the included
1276N/A<
span class="quote">“<
span class="quote"><
code class="filename">
pc/
latin</
code></
span>”</
span> file to
1276N/A<
span class="quote">“<
span class="quote"><
code class="literal">FOUR_LEVEL_ALPHABETIC</
code></
span>”</
span>. The only exception is
1056N/A<
span class="keycode"><RALT></
span> keycode which is explicitly set
1276N/A<
span class="quote">“<
span class="quote"><
code class="literal">TWO_LEVEL</
code></
span>”</
span> keytype.
1056N/AAll those names refer to pre-defined shift level schemes. Usually you can
1056N/Achoose a suitable shift level scheme from <
code class="literal">default</
code> types scheme list
1056N/Ain proper xkb component's subdirectory.
1276N/A </
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>
1056N/AThe key does not depend on any modifiers. The symbol from first level
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">TWO_LEVEL</
span></
p></
td><
td><
p>
1056N/AThe key uses a modifier Shift and may have two possible values.
1056N/AThe second level may be chosen by Shift modifier. If Lock modifier
1056N/A(usually Caps-lock) applies the symbol is further processed using
1056N/Asystem-specific capitalization rules. If both Shift+Lock modifier apply the
1056N/Asymbol from the second level is taken and capitalization rules are applied
1056N/A(and usually have no effect).
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">ALPHABETIC</
span></
p></
td><
td><
p>
1056N/AThe key uses modifiers Shift and Lock. It may have two possible
1056N/Avalues. The second level may be chosen by Shift modifier. When Lock
1056N/Amodifier applies, the symbol from the first level is taken and further
1056N/Aprocessed using system-specific capitalization rules. If both Shift+Lock
1056N/Amodifier apply the symbol from the first level is taken and no
1056N/Acapitalization rules applied. This is often called shift-cancels-caps
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">THREE_LEVEL</
span></
p></
td><
td><
p>
1056N/AIs the same as TWO_LEVEL but it considers an extra modifier -
1056N/ALevelThree which can be used to gain the symbol value from the third
1056N/Alevel. If both Shift+LevelThree modifiers apply the value from the third
1056N/Alevel is also taken. As in TWO_LEVEL, the Lock modifier doesn't influence
1056N/Athe resulting level. Only Shift and LevelThree are taken into that
1056N/Aconsideration. If the Lock modifier is active capitalization rules
1056N/Aare applied on the resulting symbol.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">FOUR_LEVEL</
span></
p></
td><
td><
p>
1056N/AIs the same as THREE_LEVEL but unlike LEVEL_THREE if both Shift+LevelThree
1056N/Amodifiers apply the symbol is taken from the fourth level.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">FOUR_LEVEL_ALPHABETIC</
span></
p></
td><
td><
p>
1056N/AIs similar to FOUR_LEVEL but also defines shift-cancels-caps behaviour
1056N/Aas in ALPHABETIC. If Lock+LevelThree apply the symbol from the
1056N/Athird level is taken and the capitalization rules are applied.
1056N/AIf Lock+Shift+LevelThree apply the symbol from the third level is taken
1056N/Aand no capitalization rules are applied.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">KEYPAD</
span></
p></
td><
td><
p>
1056N/AAs the name suggest this scheme is primarily used for numeric keypads.
1056N/AThe scheme considers two modifiers - Shift and NumLock. If none
1056N/Aof modifiers applies the symbol from the first level is taken. If either
1056N/AShift or NumLock modifiers apply the symbol from the second level is taken.
1056N/AIf both Shift+NumLock modifiers apply the symbol from the first level
1056N/Ais taken. Again, shift-cancels-caps variant.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">FOUR_LEVEL_KEYPAD</
span></
p></
td><
td><
p>
1056N/AIs similar to KEYPAD scheme but considers also LevelThree modifier.
1056N/AIf LevelThree modifier applies the symbol from the third level is taken.
1056N/AIf Shift+LevelThree or NumLock+LevelThree apply the symbol from the fourth
1056N/Alevel is taken. If all Shift+NumLock+LevelThree modifiers apply the symbol
1056N/Afrom the third level is taken. This also, shift-cancels-caps variant.
1056N/A </
p></
td></
tr></
tbody></
table></
div><
p>
1056N/ABesides that, there are several schemes for special purposes:
1276N/A </
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>
1056N/AIt is similar to TWO_LEVEL scheme but it considers the Control
1056N/Amodifier rather than Shift. That means, the symbol from the second level
1056N/Ais chosen by Control rather than by Shift.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">PC_SYSRQ</
span></
p></
td><
td><
p>
1056N/AIt is similar to TWO_LEVEL scheme but it considers the Alt modifier rather
1056N/Athan Shift. That means, the symbol from the second level
1056N/Ais chosen by Alt rather than by Shift.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">CTRL+ALT</
span></
p></
td><
td><
p>
1056N/AThe key uses modifiers Alt and Control. It may have two possible
1056N/Avalues. If only one modifier (Alt or Control) applies the symbol
1056N/Afrom the first level is chosen. Only if both Alt+Control modifiers apply
1056N/Athe symbol from the second level is chosen.
1276N/A </
p></
td></
tr><
tr><
td><
p><
span class="term">SHIFT+ALT</
span></
p></
td><
td><
p>
1056N/AThe key uses modifiers Shift and Alt. It may have two possible values.
1056N/AIf only one modifier (Alt or Shift) applies the symbol
1056N/Afrom the first level is chosen. Only if both Alt+Shift modifiers apply
1056N/Athe symbol from the second level is chosen.
1056N/A </
p></
td></
tr></
tbody></
table></
div><
p>
1056N/AIf needed, special <
code class="literal">caps</
code> schemes may be used.
1056N/AThey redefine the standard behaviour of all
1056N/A<
code class="literal">*ALPHABETIC</
code> types. The layouts (maps of
1056N/Asymbols) with keys defined in respective types then automatically change
1056N/Atheir behaviour accordingly. Possible redefinitions are:
1276N/A </
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>
1056N/ANone of these schemes should be used directly. They are defined merely
1056N/Afor <
code class="literal">'caps:'</
code> xkb options (used to globally
1056N/Achange the layouts behaviour).
1056N/ADon't alter any of existing key types. If you need a different behaviour
1276N/A </
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>
1056N/AWhen the XKB software deals with a separate type description it gets
1056N/Aa complete list of modifiers that should be taken into account from the
1056N/A<
code class="literal">'modifiers=<list of modifiers>'</
code> list and expects that a set
1056N/Aof <
code class="literal">'map[<combination of modifiers>]=<list of modifiers>'</
code>
1056N/Ainstructions that contain the mapping for each combination of modifiers
1056N/Amentioned in that list. Modifiers that are not explicitly listed are NOT taken
1056N/Awhen the resulting shift level is computed.
1056N/AIf some combination is omitted the program (subroutine) should choose the first
1056N/Alevel for this combination (a quite reasonable behavior).
1056N/ALets consider an example with two modifiers <
span class="keysym">ModOne</
span> and
1056N/A<
span class="keysym">ModTwo</
span>:
1056N/AIn this case the map statements for <
span class="keysym">ModTwo</
span> only and
1056N/A<
span class="keysym">ModOne+ModTwo</
span> are omitted. It means that if
1056N/Athe <
span class="keysym">ModTwo</
span> is active the subroutine can't found
1056N/Aexplicit mapping for such combination an will use
1056N/Athe <
span class="emphasis"><
em>default level</
em></
span>
i.e. Level1.
1056N/ABut in the case the type described as:
1056N/Athe ModTwo will not be taken into account and the resulting level depends on
1056N/Athe ModOne state only. That means, ModTwo alone produces the Level1 but the
1056N/Acombination ModOne+ModTwo produces the Level2 as well as ModOne alone.
1056N/AWhat does it mean if the second modifier is the Lock? It means that in
1056N/Athe first case (the Lock itself is included in the list of modifiers but
1056N/Acombinations with this modifier aren't mentioned in the map statements)
1056N/Athe internal capitalization rules will be applied to the symbol from the first
1056N/Alevel. But in the second case the capitalization will be applied to the symbol
1056N/Achosen accordingly to he first modifier - and this can be the symbol from the
1056N/Afirst as well as from the second level.
1056N/AUsually, all modifiers introduced in <
code class="literal">'modifiers=<list of modifiers>'</
code> list are used for shift level calculation and then
1056N/Adiscarded. Sometimes this is not desirable. If you want to use a modifier
1056N/Afor shift level calculation but you don't want to discard it, you may
1056N/Alist in '<
code class="literal">preserve[<combination of modifiers>]=<list of modifiers>'</
code>. That means, for a given combination all listed modifiers
1056N/Awill be preserved. If the Lock modifier is preserved then the resulting
1056N/Asymbol is passed to internal capitalization routine regardless whether
1056N/Ait has been used for a shift level calculation or not.
1056N/AAny key type description can use both real and virtual modifiers. Since real
1056N/Amodifiers always have standard names it is not necessary to explicitly declare
1056N/Athem. Virtual modifiers can have arbitrary names and can be declared (prior
1056N/Ausing them) directly in key type definition:
1056N/Avirtual_modifiers <comma-separated list of modifiers> ;
1056N/Aas seen in for example <
code class="literal">basic</
code>, <
code class="literal">pc</
code> or <
code class="literal">mousekeys</
code> key
1276N/A </
p></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Rules"></
a>Rules</
h3></
div></
div></
div><
p>
1056N/AOnce you are finished with your symbol map you need to add it
1056N/Ato rules file. The rules file describes how all the
1056N/Afive basic keycodes, types, compat, symbols and geometry components
1056N/Ashould be composed to give a sensible resulting xkb configuration.
1056N/AThe main advantage of rules over formerly used keymaps is a possibility
1056N/Ato simply parameterize (once) fixed patterns of configurations and thus
1056N/Ato elegantly allow substitutions of various local configurations
1056N/AA pattern in a rules file (often located in
1056N/A can be parameterized with four other arguments:
1056N/A<
code class="literal">Model</
code>, <
code class="literal">Layout</
code>,
1056N/A<
code class="literal">Variant</
code> and <
code class="literal">Options</
code>.
1056N/AFor most cases parameters <
code class="literal">model</
code> and
1056N/A<
code class="literal">layout</
code> should
1056N/Abe sufficient for choosing a functional keyboard mapping.
1056N/AThe rules file itself is composed of pattern lines and lines with rules. The
1056N/Apattern line starts with an exclamation mark ('<
code class="literal">!</
code>')
1056N/Aand describes how will the xkb interpret the following lines (rules). A sample
1056N/A caps:internal = +caps(internal)
1056N/A caps:internal_nocancel = +caps(internal_nocancel)
1056N/AEach rule defines what certain combination of values on the left side
1056N/Aof equal sign ('<
code class="literal">=</
code>') results in. For
1056N/Aexample a (keyboard) model <
code class="literal">macintosh_old</
code>
1056N/Ainstructs xkb to take definitions of keycodes from
1056N/Aof models (represented by a wild card '<
code class="literal">*</
code>')
1056N/AThe wild card represents all possible values on the left side which
1056N/Awere not found in any of the previous rules. The more specialized
1056N/A(more complete) rules have higher precedence than general ones,
1056N/Ai.e. the more general rules supply reasonable default values.
1056N/AAs you can see some lines contain substitution parameters - the parameters
1056N/Apreceded by the percent sign ('<
code class="literal">%</
code>').
1056N/AThe first alphabetical character after the percent sign expands to the
1056N/Avalue which has been found on the left side. For
1056N/Aexample <
code class="literal">+%l%(v)</
code> expands
1056N/Ainto <
code class="literal">+cz(bksl)</
code> if the respective values
1056N/Aon the left side were <
code class="literal">cz</
code> layout in
1056N/Aits <
code class="literal">bksl</
code> variant. More, if the layout
1056N/Aresp. variant parameter is followed by a pair of brackets
1056N/A('<
code class="literal">[</
code>', '<
code class="literal">]</
code>')
1056N/Ait means that xkb should <
span class="emphasis"><
em>place the layout resp. variant into
1056N/Aspecified xkb group</
em></
span>. If the brackets are omitted the first
1056N/ASo the second block of rules enhances symbol definitions for some particular
1056N/Akeyboard models with extra keys (for internet, multimedia, ...) . Other models
1056N/Aare left intact. Similarly, the last block overrides some key type definitions,
1056N/Aso the common global behaviour ''shift cancels caps'' or ''shift doesn't cancel
1056N/Acaps'' can be selected. The rest of rules produces special symbols for each
1056N/Avariant <
code class="literal">us</
code> layout of
1056N/A<
code class="literal">macintosh</
code> keyboard and standard pc
1056N/Asymbols in appropriate variants as a default.
1276N/A </
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>
1056N/ANow you just need to add a detailed description to
1056N/A<
code class="filename"><rules>.xml</
code>
1056N/Adescription file so the other users (and external programs which often parse
1056N/Athis file) know what is your work about.
1276N/A </
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>
1056N/AThe formerly used descriptive files were named <
code class="filename"><rules>.lst</
code>
1056N/AIts structure is very simple and quite self descriptive but such simplicity
1056N/Ahad also some cavities, for example there was no way how to describe local
1056N/Avariants of layouts and there were problems with the localization of
1056N/Adescriptions. To preserve compatibility with some older programs,
1056N/Anew XML descriptive files can be converted to old format '.lst'.
1056N/AFor each parameter of rules file should be described its meaning. For the rules
1056N/Afile described above the <
code class="filename">.lst</
code> file could look like:
1056N/A microsoft Microsoft Natural
1056N/A macintosh Original Macintosh
1056N/A caps:internal uses internal capitalization. Shift cancels Caps
1056N/A caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
1056N/AAnd that should be it. Enjoy creating your own xkb mapping.
1056N/A </
p></
div></
div></
div></
div></
body></
html>