From 46215bfc9c142f5f32aad1cc54d49ee1d69a1980 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Fri, 10 May 2019 11:44:40 +0000 Subject: Install more manual pages: * XKB-Config(7), XKB-Enhancing(7): user-level documentation for XKB configuration; not perfect, but the best available. * xtrans(3): a library actively maintained upstream. * libXmu and libXext: Many libraries are effectively frozen upstream. According to matthieu@, the documentation of libXmu and libXext is among the most valuable of those. Feedback and OK matthieu@. --- doc/xorg-docs/Makefile.bsd-wrapper | 6 +- doc/xorg-docs/general/input/XKB-Config.7 | 239 ++++++++++ doc/xorg-docs/general/input/XKB-Enhancing.7 | 672 ++++++++++++++++++++++++++++ doc/xorg-docs/general/input/defs.ent | 1 + 4 files changed, 916 insertions(+), 2 deletions(-) create mode 100644 doc/xorg-docs/general/input/XKB-Config.7 create mode 100644 doc/xorg-docs/general/input/XKB-Enhancing.7 create mode 100644 doc/xorg-docs/general/input/defs.ent (limited to 'doc') diff --git a/doc/xorg-docs/Makefile.bsd-wrapper b/doc/xorg-docs/Makefile.bsd-wrapper index 075b2b6c0..f1a5b1091 100644 --- a/doc/xorg-docs/Makefile.bsd-wrapper +++ b/doc/xorg-docs/Makefile.bsd-wrapper @@ -1,8 +1,10 @@ -# $OpenBSD: Makefile.bsd-wrapper,v 1.5 2019/05/05 23:27:58 schwarze Exp $ +# $OpenBSD: Makefile.bsd-wrapper,v 1.6 2019/05/10 11:44:39 schwarze Exp $ CONFIGURE_ARGS += --without-fop --without-xmlto -MDOCS = general/fonts/fonts +MDOCS = general/fonts/fonts \ + general/input/XKB-Config \ + general/input/XKB-Enhancing beforeinstall: .for n in ${MDOCS} diff --git a/doc/xorg-docs/general/input/XKB-Config.7 b/doc/xorg-docs/general/input/XKB-Config.7 new file mode 100644 index 000000000..44979185d --- /dev/null +++ b/doc/xorg-docs/general/input/XKB-Config.7 @@ -0,0 +1,239 @@ +.\" automatically generated with docbook2mdoc XKB-Config.xml +.Dd November 2010 +.Dt XKB-CONFIG 7 +.Os +.Sh NAME +.Nm XKB-Config +.Nd The XKB Configuration Guide +.Sh ABSTRACT +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. +.Pp +This version covers Xorg server versions 1.8 and later, used with the +data files from the +.Lk http://www.freedesktop.org/wiki/Software/XKeyboardConfig xkeyboard-config +project. +.Sh OVERVIEW +The XKB configuration is decomposed into a number of components. +Selecting +proper parts and combining them back you can achieve most of the configurations +you might need. +Unless you have a completely atypical keyboard you really don't +need to touch any of the xkb configuration files. +.Pp +Some desktop environments now provide integrated graphical configuration +tools for setting XKB configuration as part of your desktop session. +The +instructions in this document are provided for those without such support, +those who need to configure XKB before the session startup (such as at the +login screen), or those who need to perform more advanced configuration +than those tools provide. +.Sh SELECTING XKB CONFIGURATION +The easiest and the most natural way to specify a keyboard mapping is to use +the +.Ql rules +component. +As its name suggests it describes a number of +general rules to combine all bits and pieces into a valid and useful keyboard +mapping. +All you need to do is to select a suitable rules file and then to +feed it with a few parameters that will adjust the keyboard behaviour to +fulfill your needs. +.Pp +The parameters are: +.Bl -tag -width Ds +.It Fl XkbRules +files of rules to be used for keyboard mapping composition +.It Fl XkbModel +name of the model of your keyboard type +.It Fl XkbLayout +layout(s) you intend to use +.It Fl XkbVariant +variant(s) of the layout you intend to use +.It Fl XkbOptions +extra xkb configuration options +.El +.Pp +The rules file used depends on your system. +The rules files commonly +used with Xorg are provided by the +.Lk http://www.freedesktop.org/wiki/Software/XKeyboardConfig xkeyboard-config +project. +On Linux systems, the +.Pa evdev +rules are most +commonly used, on other systems the +.Pa base +rules +are used. +Some additional rules files exist for historical reasons, +but are no longer widely used. +In general, it's best to simply not +specify the rules file, in order to use the default rules selected +automatically by the X server. +.Pp +For each rules file there is a description file named +.Pa < Ns Ar vendor-rules Ns > . Ns lst , +for instance +.Pa base.lst +which is located in +the xkb configuration subdirectory +.Pa rules +(for example +.Pa /usr/share/X11/xkb/rules ) . +.Ss Basic Configuration +Let's say you want to configure a PC-style American keyboard with 104 +keys as described in +.Pa base.lst . +This can be done +by simply writing several lines from below to a new configuration file +in +.Pa /etc/X11/xorg.conf.d , +such +as +.Pa /etc/X11/xorg.conf.d/90-custom-kbd.conf . +.Bd -literal +Section "InputClass" + Identifier "keyboard defaults" + MatchIsKeyboard "on" + Option "XkbModel" "pc104" + Option "XkbLayout" "us" + Option "XKbOptions" "" +EndSection +.Ed +.Pp +The values of +.Fl XkbModel +and +.Fl XkbLayout +are +really not surprising. +The +.Fl XkbOptions +has been explicitly set to the empty set of parameters. +The +.Fl XkbVariant +option has been left out. +That means the default variant named +.Ql basic +is loaded. +.Pp +Of course, this can be also done at runtime using the utility +.Nm setxkbmap . +The shell command loading the same keyboard mapping would look like: +.Bd -literal +setxkbmap -model pc104 -layout us -option "" +.Ed +.Pp +The configuration and the shell command would be very analogous +for most other layouts (internationalized mappings). +.Pp +If you wanted to enable the +.Sy Ctrl +.Sy Alt Ns Sy Backspace +sequence to kill +the X server by default, you could create a configuration snippet +.Pa /etc/X11/xorg.conf.d/90-zap.conf +containing: +.Bd -literal +Section "InputClass" + Identifier "keyboard defaults" + MatchIsKeyboard "on" + Option "XKbOptions" "terminate:ctrl_alt_bksp" +EndSection +.Ed +.Pp +This would be equivalent to running the shell command: +.Bd -literal +setxkbmap -option "terminate:ctrl_alt_bksp" +.Ed +.Ss Advanced Configuration +You can use multi-layouts xkb configuration. +What does it mean? +Basically it allows to load up to four different +keyboard layouts at a time. +Each such layout would reside in its +own group. +The groups (unlike complete keyboard remapping) can be +switched very fast from one to another by a combination of keys. +.Pp +Let's say you want to configure your new Logitech cordless desktop +keyboard, you intend to use three different layouts at the same +time - us, czech and german (in this order), and that you are used to +.Sy Alt Ns Sy Shift +combination for switching among them. +.Pp +Then the configuration snippet could look like this: +.Bd -literal +Section "InputClass" + Identifier "Logitech Cordless" + MatchIsKeyboard "on" + Option "XkbModel" "logicordless" + Option "XkbLayout" "us,cz,de" + Option "XKbOptions" "grp:alt_shift_toggle" +EndSection +.Ed +.Pp +Of course, this can be also done at runtime using the utility +.Nm setxkbmap . +The shell command loading the same keyboard mapping would look like: +.Bd -literal +setxkbmap -model logicordless -layout "us,cz,de" \e + -option "grp:alt_shift_toggle" +.Ed +.Ss Even More Advanced Configuration +Okay, let's say you are more demanding. +You do like the example +above but you want it to change a bit. +Let's imagine you want +the czech keyboard mapping to use another variant but basic. +The configuration snippet then changes into: +.Bd -literal +Section "InputClass" + Identifier "Logitech Cordless" + MatchIsKeyboard "on" + Option "XkbModel" "logicordless" + Option "XkbLayout" "us,cz,de" + Option "XkbVariant" ",bksl," + Option "XKbOptions" "grp:alt_shift_toggle" EndSection +.Ed +.Pp +That seems tricky but it is not. +The logic for settings of variants +is the same as for layouts, that means the first and the third variant +settings are left out (set to +.Ql basic ) , +the second is set to +.Ql bksl +(a special +variant with an enhanced definition of the backslash key). +.Pp +Analogously, the loading runtime will change to: +.Bd -literal +setxkbmap -model logicordless -layout "us,cz,de" \e + -variant ",bksl," -option "grp:alt_shift_toggle" +.Ed +.Ss Basic Global Options +For a list of available options, with a short description of what they do, +see the section starting with +.Dq Li ! option +in the +.Pa rules/*.lst +files. +.Sh KEYMAP XKB CONFIGURATION +Keymap configuration is the way formerly used to configure xkb. +The +user included a special keymap file which specified the direct xkb +configuration. +This method has been obsoleted by previously described +rules files which are far more flexible and allow simpler and more +intuitive syntax. +It is preserved merely for compatibility reasons and +should be avoided if possible. +.Sh AUTHORS +.An -nosplit +X Version 11, Release 6 +.An -split +.An Kamil Toman +.An Ivan U. Pascal diff --git a/doc/xorg-docs/general/input/XKB-Enhancing.7 b/doc/xorg-docs/general/input/XKB-Enhancing.7 new file mode 100644 index 000000000..8b6b076ef --- /dev/null +++ b/doc/xorg-docs/general/input/XKB-Enhancing.7 @@ -0,0 +1,672 @@ +.\" automatically generated with docbook2mdoc XKB-Enhancing.xml +.Dd 25 November 2002 +.Dt XKB-ENHANCING 7 +.Os +.Sh NAME +.Nm XKB-Enhancing +.Nd How to further enhance XKB configuration +.Sh ABSTRACT +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. +.Sh OVERVIEW +The developer of a new layout should read the xkb +protocol specification +.Pf ( Lk http://www.x.org/docs/XKB/XKBproto.pdf "The X Keyboard Extension: Protocol Specification" ) +at least +to clarify for himself some xkb-specific terms used in this document +and elsewhere in xkb configuration. +Also it shows wise to understand +how the X server and a client digest their keyboard inputs +(with and without xkb). +.Pp +A useful source is also +.Lk http://www.tsu.ru/~pascal/en/xkb "Ivan Pascal's text about xkb configuration" +often referenced throughout this +document. +.Pp +Note that this document covers only enhancements which +are to be made to XFree86 version 4.3 and X11R6.7.0 and above. +.Sh THE BASICS +At the startup (or at later at user's command) X server starts its xkb +keyboard module extension and reads data from a compiled configuration +file. +.Pp +This compiled configuration file is prepared by the +program +.Nm xkbcomp +which behaves altogether as an +ordinary compiler (see +.Ql man xkbcomp ) . +Its input are human readable xkb configuration files which are verified and +then composed into a useful xkb configuration. +Users don't need to mess with +.Nm xkbcomp +themselves, for them it is invisible. +Usually, +it is started upon X server startup. +.Pp +As you probably already know, the xkb configuration consists of five +main modules: +.Bl -tag -width Ds +.It Keycodes +Tables that defines translation from keyboard scan codes into reasonable +symbolic names, maximum, minimum legal keycodes, symbolic aliases and +description of physically present LED-indicators. +The primary sense of +this component is to allow definitions of maps of symbols (see below) +to be independent of physical keyboard scancodes. +There are two main +naming conventions for symbolic names (always four bytes long): +.Bl -bullet +.It +names which express some traditional meaning like + (stands for space bar) or +.It +names which express some relative positioning on a keyboard, for +example (an exclamation mark on US keyboards), on +the right there are keys , +etc. +.El +.It Types +Types describe how the produced key is changed by active modifiers (like +Shift, Control, Alt, ...). There are several predefined types which +cover most of used combinations. +.It Compat +Compatibility component defines internal behaviour of modifiers. +Using +compat component you can assign various actions (elaborately described +in xkb specification) to key events. +This is also the place where +LED-indicators behaviour is defined. +.It Symbols +For i18n purposes, this is the most important table. +It defines what +values (=symbols) are assigned to what keycodes (represented by their +symbolic name, see above). There may be defined more than one value +for each key and then it depends on a key type and on modifiers state +(respective compat component) which value will be the resulting one. +.It Geometry +Geometry files aren't used by xkb itself but they may be used by some +external programs to depict a keyboard image. +.El +.Pp +All these components have the files located in xkb configuration tree +in subdirectories with the same names (usually in +.Pa /usr/lib/X11/xkb ) . +.Sh ENHANCING XKB CONFIGURATION +Most of xkb enhancements concerns a need to define new output symbols +for the some input key events. +In other words, a need to define a new +symbol map (for a new language, standard or just to feel more comfortable +when typing text). +.Pp +What do you need to do? +Generally, you have to define following things: +.Bl -bullet +.It +the map of symbols itself +.It +the rules to allow users to select the new mapping +.It +the description of the new layout +.El +.Pp +First of all, it is good to go through existing layouts and to examine +them if there is something you could easily adjust to fit your needs. +Even if there is nothing similar you may get some ideas about basic +concepts and used tricks. +.Ss Levels And Groups +Since XFree86 4.3.0 and X11R6.7.0 you can use +.Em multi-layout +concept of xkb +configuration. +Though it is still in boundaries of xkb protocol and general ideas, the +keymap designer must obey new rules when creating new maps. +In exchange +we get a more powerful and cleaner configuration system. +.Pp +Remember that it is the application which must decide which symbol +matches which keycode according to effective modifier state. +The X server +itself sends only an input event message to. +Of course, usually +the general interpretation is processed by Xlib, Xaw, Motif, Qt, Gtk +and similar libraries. +The X server only supplies its mapping table +(usually upon an application startup). +.Pp +You can think of the X server's symbol table as of a irregular table where each +keycode has its row and where each combination of modifiers determines exactly +one column. +The resulting cell then gives the proper symbolic value. +Not all +keycodes need to bind different values for different combination of modifiers. + key, for instance, usually doesn't depend on any +modifiers so it its row has only one column defined. +.Pp +Note that in XKB there is no prior assumption that certain modifiers are bound +to certain columns. +By editing proper files (see +.Sx Key_Types ) +this mapping can be changed as well. +.Pp +Unlike the original X protocol the XKB approach is far more +flexible. +It is comfortable to add one additional XKB term - group. +You can +think of a group as of a vector of columns per each keycode (naturally the +dimension of this vector may differ for different keycodes). What is it good +for? +The group is not very useful unless you intend to use more than one +logically different set of symbols (like more than one alphabet) defined in a +single mapping table. +But then, the group has a natural meaning - each symbol +set has its own group and changing it means selecting a different one. +XKB approach allows up to four different groups. +The columns inside each group +are called (shift) levels. +The X server knows the current group and reports it +together with modifier set and with a keycode in key events. +.Pp +To sum it up: +.Bl -bullet +.It +for each keycode XKB keyboard map contains up to four one-dimensional +tables - groups (logically different symbol sets) +.It +for each group of a keycode XKB keyboard map contains some columns +- shift levels (values reached by combinations of Shift, Ctrl, Alt, ... +modifiers) +.It +different keycodes can have different number of groups +.It +different groups of one keycode can have different number of shift levels +.It +the current group number is tracked by X server +.El +.Pp +It is clear that if you sanely define levels, groups and sanely bind +modifiers and associated actions you can have simultaneously loaded up to +four different symbol sets where each of them would reside in its own group. +.Pp +The multi-layout concept provides a facility to manipulate xkb groups +and symbol definitions in a way that allows almost arbitrary composition of +predefined symbol tables. +To keep it fully functional you have to: +.Bl -bullet +.It +define all symbols only in the first group +.It +(re)define any modifiers with extra care to avoid strange (anisometric) +behaviour +.El +.Sh DEFINING NEW LAYOUTS +See +.Lk http://www.tsu.ru/~pascal/en/xkb/internals.html "Some Words About XKB internals" +for explanation of used xkb terms and problems +addressed by XKB extension. +.Pp +See +.Lk http://www.tsu.ru/~pascal/en/xkb/gram-common.html "Common notes about XKB configuration files language" +for more precise explanation of +syntax of xkb configuration files. +.Ss Predefined XKB Symbol Sets +If you are about to define some European symbol map extension, you might +want to use on of four predefined latin alphabet layouts. +.Pp +Okay, let's assume you want extend an existing keymap and you want to override +a few keys. +Let's take a simple U.K. keyboard as an example (defined in +.Pa pc/gb ) : +.Bd -literal +partial default alphanumeric_keys +xkb_symbols "basic" { + include "pc/latin" + name[Group1]="Great Britain"; + key \[u003C]AE02\[u003E] { [ 2, quotedbl, twosuperior, oneeighth ] }; + key \[u003C]AE03\[u003E] { [ 3, sterling, threesuperior, sterling ] }; + key \[u003C]AC11\[u003E] { [apostrophe, at, dead_circumflex, dead_caron] }; + key \[u003C]TLDE\[u003E] { [ grave, notsign, bar, bar ] }; + key \[u003C]BKSL\[u003E] { [numbersign, asciitilde, dead_grave, dead_breve ] }; + key \[u003C]RALT\[u003E] { type[Group1]="TWO_LEVEL", + [ ISO_Level3_Shift, Multi_key ] }; + modifier_map Mod5 { \[u003C]RALT\[u003E] }; +}; +.Ed +.Pp +It defines a new layout in +.Ql basic +variant as an extension of common +latin alphabet layout. +The layout (symbol set) name is set to "Great Britain". +Then there are redefinitions of a few keycodes and a modifiers binding. +As you +can see the number of shift levels is the same for +, , +, and + keys but it differs from number of shift +levels of . +.Pp +Note that the key itself is a binding key for Mod5 and +that it +serves like a shift modifier for LevelThree, together with Shift +as a multi-key. +It is a good habit to respect this rule in a new similar +layout. +.Pp +Okay, you could now define more variants of your new layout besides +.Ql basic +simply by including (augmenting/overriding/...) +the basic +definition and altering what may be needed. +.Ss Key Types +The differences in the number of columns (shift levels) are caused by +a different types of keys (see the types definition in section basics). Most +keycodes have implicitly set the keytype in the included +.Pa pc/latin +file to +.Dq Li FOUR_LEVEL_ALPHABETIC . +The only exception is + keycode which is explicitly set +.Dq Li TWO_LEVEL +keytype. +.Pp +All those names refer to pre-defined shift level schemes. +Usually you can +choose a suitable shift level scheme from +.Ql default +types scheme list +in proper xkb component's subdirectory. +.Pp +The most used schemes are: +.Bl -tag -width Ds +.It ONE_LEVEL +The key does not depend on any modifiers. +The symbol from first level +is always chosen. +.It TWO_LEVEL +The key uses a modifier Shift and may have two possible values. +The second level may be chosen by Shift modifier. +If Lock modifier +(usually Caps-lock) applies the symbol is further processed using +system-specific capitalization rules. +If both Shift+Lock modifier apply the +symbol from the second level is taken and capitalization rules are applied +(and usually have no effect). +.It ALPHABETIC +The key uses modifiers Shift and Lock. +It may have two possible +values. +The second level may be chosen by Shift modifier. +When Lock +modifier applies, the symbol from the first level is taken and further +processed using system-specific capitalization rules. +If both Shift+Lock +modifier apply the symbol from the first level is taken and no +capitalization rules applied. +This is often called shift-cancels-caps +behaviour. +.It THREE_LEVEL +Is the same as TWO_LEVEL but it considers an extra modifier - +LevelThree which can be used to gain the symbol value from the third +level. +If both Shift+LevelThree modifiers apply the value from the third +level is also taken. +As in TWO_LEVEL, the Lock modifier doesn't influence +the resulting level. +Only Shift and LevelThree are taken into that +consideration. +If the Lock modifier is active capitalization rules +are applied on the resulting symbol. +.It FOUR_LEVEL +Is the same as THREE_LEVEL but unlike LEVEL_THREE if both Shift+LevelThree +modifiers apply the symbol is taken from the fourth level. +.It FOUR_LEVEL_ALPHABETIC +Is similar to FOUR_LEVEL but also defines shift-cancels-caps behaviour +as in ALPHABETIC. +If Lock+LevelThree apply the symbol from the +third level is taken and the capitalization rules are applied. +If Lock+Shift+LevelThree apply the symbol from the third level is taken +and no capitalization rules are applied. +.It KEYPAD +As the name suggest this scheme is primarily used for numeric keypads. +The scheme considers two modifiers - Shift and NumLock. +If none +of modifiers applies the symbol from the first level is taken. +If either +Shift or NumLock modifiers apply the symbol from the second level is taken. +If both Shift+NumLock modifiers apply the symbol from the first level +is taken. +Again, shift-cancels-caps variant. +.It FOUR_LEVEL_KEYPAD +Is similar to KEYPAD scheme but considers also LevelThree modifier. +If LevelThree modifier applies the symbol from the third level is taken. +If Shift+LevelThree or NumLock+LevelThree apply the symbol from the fourth +level is taken. +If all Shift+NumLock+LevelThree modifiers apply the symbol +from the third level is taken. +This also, shift-cancels-caps variant. +.El +.Pp +Besides that, there are several schemes for special purposes: +.Bl -tag -width Ds +.It PC_BREAK +It is similar to TWO_LEVEL scheme but it considers the Control +modifier rather than Shift. +That means, the symbol from the second level +is chosen by Control rather than by Shift. +.It PC_SYSRQ +It is similar to TWO_LEVEL scheme but it considers the Alt modifier rather +than Shift. +That means, the symbol from the second level +is chosen by Alt rather than by Shift. +.It CTRL+ALT +The key uses modifiers Alt and Control. +It may have two possible +values. +If only one modifier (Alt or Control) applies the symbol +from the first level is chosen. +Only if both Alt+Control modifiers apply +the symbol from the second level is chosen. +.It SHIFT+ALT +The key uses modifiers Shift and Alt. +It may have two possible values. +If only one modifier (Alt or Shift) applies the symbol +from the first level is chosen. +Only if both Alt+Shift modifiers apply +the symbol from the second level is chosen. +.El +.Pp +If needed, special +.Ql caps +schemes may be used. +They redefine the standard behaviour of all +.Ql *ALPHABETIC +types. +The layouts (maps of +symbols) with keys defined in respective types then automatically change +their behaviour accordingly. +Possible redefinitions are: +.Bl -bullet +.It +internal +.It +internal_nocancel +.It +shift +.It +shift_nocancel +.El +.Pp +None of these schemes should be used directly. +They are defined merely +for +.Ql 'caps:' +xkb options (used to globally +change the layouts behaviour). +.Pp +Don't alter any of existing key types. +If you need a different behaviour +create a new one. +.Pp +.Sy More \&On Definitions \&Of Types +.Pp +When the XKB software deals with a separate type description it gets +a complete list of modifiers that should be taken into account from the +.Ql 'modifiers=' +list and expects that a set +of +.Ql 'map[]=' +instructions that contain the mapping for each combination of modifiers +mentioned in that list. +Modifiers that are not explicitly listed are NOT taken +into account +when the resulting shift level is computed. +If some combination is omitted the program (subroutine) should choose the first +level for this combination (a quite reasonable behavior). +.Pp +Lets consider an example with two modifiers +.Sy ModOne +and +.Sy ModTwo : +.Bd -literal +type "..." { + modifiers = ModOne+ModTwo; + map[None] = Level1; + map[ModOne] = Level2; +}; +.Ed +.Pp +In this case the map statements for +.Sy ModTwo +only and +.Sy ModOne+ModTwo +are omitted. +It means that if +the +.Sy ModTwo +is active the subroutine can't found +explicit mapping for such combination an will use +the +.Em default level +i.e. Level1. +.Pp +But in the case the type described as: +.Bd -literal +type "..." { + modifiers = ModOne; + map[None] = Level1; + map[ModOne] = Level2; +}; +.Ed +.Pp +the ModTwo will not be taken into account and the resulting level depends on +the ModOne state only. +That means, ModTwo alone produces the Level1 but the +combination ModOne+ModTwo produces the Level2 as well as ModOne alone. +.Pp +What does it mean if the second modifier is the Lock? +It means that in +the first case (the Lock itself is included in the list of modifiers but +combinations with this modifier aren't mentioned in the map statements) +the internal capitalization rules will be applied to the symbol from the first +level. +But in the second case the capitalization will be applied to the symbol +chosen accordingly to the first modifier - and this can be the symbol from the +first as well as from the second level. +.Pp +Usually, all modifiers introduced in +.Ql 'modifiers=' +list are used for shift level calculation and then +discarded. +Sometimes this is not desirable. +If you want to use a modifier +for shift level calculation but you don't want to discard it, you may +list in +.Pf ' Ql preserve[]=' . +That means, for a given combination all listed modifiers +will be preserved. +If the Lock modifier is preserved then the resulting +symbol is passed to internal capitalization routine regardless whether +it has been used for a shift level calculation or not. +.Pp +Any key type description can use both real and virtual modifiers. +Since real +modifiers always have standard names it is not necessary to explicitly declare +them. +Virtual modifiers can have arbitrary names and can be declared (prior +using them) directly in key type definition: +.Bd -literal +virtual_modifiers ; +.Ed +.Pp +as seen in for example +.Ql basic , +.Ql pc +or +.Ql mousekeys +key +type definitions. +.Ss Rules +Once you are finished with your symbol map you need to add it +to rules file. +The rules file describes how all the +five basic keycodes, types, compat, symbols and geometry components +should be composed to give a sensible resulting xkb configuration. +.Pp +The main advantage of rules over formerly used keymaps is a possibility +to simply parameterize (once) fixed patterns of configurations and thus +to elegantly allow substitutions of various local configurations +into predefined templates. +.Pp +A pattern in a rules file (often located in +.Pa /usr/lib/X11/xkb/rules ) +can be parameterized with four other arguments: +.Ql Model , +.Ql Layout , +.Ql Variant +and +.Ql Options . +For most cases parameters +.Ql model +and +.Ql layout +should +be sufficient for choosing a functional keyboard mapping. +.Pp +The rules file itself is composed of pattern lines and lines with rules. +The +pattern line starts with an exclamation mark +.Pf (' Ql ! Ns ') +and describes how will the xkb interpret the following lines (rules). A sample +rules file looks like this: +.Bd -literal +! model = keycodes + macintosh_old = macintosh + ... + * = xorg +! model = symbols + hp = +inet(%m) + microsoftpro = +inet(%m) + geniuscomfy = +inet(%m) +! model layout[1] = symbols + macintosh us = macintosh/us%(v[1]) + * * = pc/pc(%m)+pc/%l[1]%(v[1]) +! model layout[2] = symbols + macintosh us = +macintosh/us[2]%(v[2]):2 + * * = +pc/%l[2]%(v[2]):2 +! option = types + caps:internal = +caps(internal) + caps:internal_nocancel = +caps(internal_nocancel) +.Ed +.Pp +Each rule defines what certain combination of values on the left side +of equal sign +.Pf (' Ql = Ns ') +results in. +For +example a (keyboard) model +.Ql macintosh_old +instructs xkb to take definitions of keycodes from +file +.Pa keycodes/macintosh +while the rest +of models (represented by a wild card +.Pf ' Ql * Ns ') +instructs it to take them from file +.Pa keycodes/xorg . +The wild card represents all possible values on the left side which +were not found in any of the previous rules. +The more specialized +(more complete) rules have higher precedence than general ones, +i.e. the more general rules supply reasonable default values. +.Pp +As you can see some lines contain substitution parameters - the parameters +preceded by the percent sign +.Pf (' Ql % Ns '). +The first alphabetical character after the percent sign expands to the +value which has been found on the left side. +For +example +.Ql +%l%(v) +expands +into +.Ql +cz(bksl) +if the respective values +on the left side were +.Ql cz +layout in +its +.Ql bksl +variant. +More, if the layout +resp. +variant parameter is followed by a pair of brackets +.Pf (' Ql [ Ns ', +.Pf ' Ql ] Ns ') +it means that xkb should +.Em place the layout resp. variant into specified xkb group . +If the brackets are omitted the first +group is the default value. +.Pp +So the second block of rules enhances symbol definitions for some particular +keyboard models with extra keys (for internet, multimedia, ...) . Other models +are left intact. +Similarly, the last block overrides some key type definitions, +so the common global behaviour ''shift cancels caps'' or ''shift doesn't cancel +caps'' can be selected. +The rest of rules produces special symbols for each +variant +.Ql us +layout of +.Ql macintosh +keyboard and standard pc +symbols in appropriate variants as a default. +.Ss Descriptive Files of Rules +Now you just need to add a detailed description to +.Pa .xml +description file so the other users (and external programs which often parse +this file) know what is your work about. +.Pp +.Sy Old Descriptive Files +.Pp +The formerly used descriptive files were named +.Pa .lst +Its structure is very simple and quite self descriptive but such simplicity +had also some cavities, for example there was no way how to describe local +variants of layouts and there were problems with the localization of +descriptions. +To preserve compatibility with some older programs, +new XML descriptive files can be converted to old format '.lst'. +.Pp +For each parameter of rules file should be described its meaning. +For the rules +file described above the +.Pa .lst +file could look like: +.Bd -literal +! model + pc104 Generic 104-key PC + microsoft Microsoft Natural + pc98 PC-98xx Series + macintosh Original Macintosh + ... +! layout + us U.S. English + cz Czech + de German + ... +! option + caps:internal uses internal capitalization. Shift cancels Caps + caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps +.Ed +.Pp +And that should be it. +Enjoy creating your own xkb mapping. +.Sh AUTHORS +.An -nosplit +X Version 11, Release 6 +.An -split +.An Kamil Toman +.An Ivan U. Pascal diff --git a/doc/xorg-docs/general/input/defs.ent b/doc/xorg-docs/general/input/defs.ent new file mode 100644 index 000000000..30b1911cd --- /dev/null +++ b/doc/xorg-docs/general/input/defs.ent @@ -0,0 +1 @@ + -- cgit v1.2.3