From e238a66114f7582422a17f7f7a5579cf70eb9388 Mon Sep 17 00:00:00 2001 From: Egbert Eich Date: Tue, 6 Apr 2004 23:33:22 +0000 Subject: Updating formatted docs. CVt: Enter Log. Lines beginning with `CVS:' are removed automatically --- README.config | 36 +++++++------- README.enhancing | 148 +++++++++++++++++++++++++++---------------------------- 2 files changed, 90 insertions(+), 94 deletions(-) diff --git a/README.config b/README.config index 4dd4d2e..588c861 100644 --- a/README.config +++ b/README.config @@ -23,23 +23,23 @@ The easiest and the most natural way how to specify a keyboard mapping is to use rules component. As its name suggests it describes a number of general rules how 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 ful­ +feed it with a few parameters that will adjust the keyboard behaviour to ful- fill your needs. The parameters are: - · XkbRules - files of rules to be used for keyboard mapping composition + o XkbRules - files of rules to be used for keyboard mapping composition - · XkbModel - name of model of your keyboard type + o XkbModel - name of model of your keyboard type - · XkbLayout - layout(s) you intend to use + o XkbLayout - layout(s) you intend to use - · XkbVariant - variant(s) of layout you intend to use + o XkbVariant - variant(s) of layout you intend to use - · XkbOptions - extra xkb configuration options + o XkbOptions - extra xkb configuration options The proper rules file depends on your vendor. In reality, the commonest file -of rules is xorg. For each rules file there is a description file named .lst, for instance xorg.lst which is located in xkb configuration subdirectory rules (for example /etc/X11/xkb/rules). @@ -147,17 +147,17 @@ occasions it may be needed, though. So how does it work? There are five basic components used to form a keyboard mapping: - · key codes - a translation of the scan codes produced by the keyboard + o key codes - a translation of the scan codes produced by the keyboard into a suitable symbolic form - · types - a specification of what various combinations of modifiers pro­ + o types - a specification of what various combinations of modifiers pro- duce - · key symbols - a translation of symbolic key codes into actual symbols + o key symbols - a translation of symbolic key codes into actual symbols - · geometry - a description of physical keyboard geometry + o geometry - a description of physical keyboard geometry - · compatibility maps - a specification of what action should each key pro­ + o compatibility maps - a specification of what action should each key pro- duce in order to preserve compatibility with XKB-unware clients 3.2 Example Configuration @@ -175,11 +175,11 @@ Look at the following example: Option "XkbCompat" "basic+pc+iso9995" EndSection -This configuration sets the standard X server default interpretation of key­ -board keycodes, sets the default modificator types. The symbol table is com­ +This configuration sets the standard X server default interpretation of key- +board keycodes, sets the default modificator types. The symbol table is com- posed of extended US keyboard layout in its variant for pc keyboards with 104 keys plus all keys for german layout are redefined respectively. Also the -logical meaning of Caps-lock and Control keys is swapped. The standard key­ +logical meaning of Caps-lock and Control keys is swapped. The standard key- board geometry (physical look) is set to pc style keyboard with 104 keys. The compatibility map is set to allow basic shifting, to allow Alt keys to be interpreted and also to allow iso9995 group shifting. @@ -188,11 +188,9 @@ interpreted and also to allow iso9995 group shifting. It is the formerly used way 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 flexi­ +been obsoleted by previously described rules files which are far more flexi- ble and allow simpler and more intuitive syntax. It is preserved merely for compatibility reasons. Avoid using it if it is possible. - $Id$ + Generated from Id: XKB-Config.sgml,v 1.1.4.1.6.2 eich Exp $ - -$XFree86$ diff --git a/README.enhancing b/README.enhancing index 9c702da..64598e9 100644 --- a/README.enhancing +++ b/README.enhancing @@ -6,7 +6,7 @@ Abstract - This guide is aimed to relieve one's labour to create a new (inter­ + This guide is aimed to relieve one's labour to create a new (inter- nationalized) keyboard layout. Unlike other documents this guide accents the keymap developer's point of view. @@ -20,7 +20,7 @@ wise to understand how the X server and a client digest their keyboard inputs (with and without xkb). A useful source is also Ivan Pascal's text about xkb configuration - often referenced throughout this docu­ + often referenced throughout this docu- ment. Note that this document covers only enhancements which are to be made to @@ -28,13 +28,13 @@ XFree86 version 4.3 and X11R6.7.0 and above. 2. The Basics -At the startup (or at later at user's command) X server starts its xkb key­ +At the startup (or at later at user's command) X server starts its xkb key- board module extension and reads data from a compiled configuration file. This compiled configuration file is prepared by the program xkbcomp which behaves altogether as an ordinary compiler (see 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 xkbcomp them­ +into a useful xkb configuration. Users don't need to mess with xkbcomp them- selves, for them it is invisible. Usually, it is started upon X server startup. @@ -43,28 +43,28 @@ modules: Keycodes Tables that defines translation from keyboard scan codes into - reasonable symbolic names, maximum, minimum legal keycodes, sym­ - bolic aliases and description of physically present LED-indica­ + reasonable symbolic names, maximum, minimum legal keycodes, sym- + bolic aliases and description of physically present LED-indica- tors. The primary sence of this component is to allow definitions - of maps of symbols (see below) to be independent of physical key­ - board scancodes. There are two main naming conventions for sym­ + of maps of symbols (see below) to be independent of physical key- + board scancodes. There are two main naming conventions for sym- bolic names (always four bytes long): - · names which express some traditional meaning like + o names which express some traditional meaning like (stands for space bar) or - · names which express some relative positioning on a key­ - board, for example (an exclamation mark on US key­ + o names which express some relative positioning on a key- + board, for example (an exclamation mark on US key- boards), on the right there are keys , etc. Types - Types describe how the produced key is changed by active modi­ - fiers (like Shift, Control, Alt, ...). There are several prede­ + Types describe how the produced key is changed by active modi- + fiers (like Shift, Control, Alt, ...). There are several prede- fined types which cover most of used combinations. Compat Compatibility component defines internal behaviour of modifiers. - Using compat component you can assign various actions (elabo­ + Using compat component you can assign various actions (elabo- rately described in xkb specification) to key events. This is also the place where LED-indicators behaviour is defined. @@ -80,7 +80,7 @@ modules: Geometry files aren't used by xkb itself but they may be used by some external programs to depict a keyboard image. -All these components have the files located in xkb configuration tree in sub­ +All these components have the files located in xkb configuration tree in sub- directories with the same names (usually in /usr/lib/X11/xkb). 3. Enhancing XKB Configuration @@ -91,11 +91,11 @@ a new language, standard or just to feel more comfortable when typing text). What do you need to do? Generally, you have to define following things: - · the map of symbols itself + o the map of symbols itself - · the rules to allow users to select the new mapping + o the rules to allow users to select the new mapping - · the description of the new layout + o the description of the new layout 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 @@ -111,7 +111,7 @@ exchange we get a more powerful and cleaner configuration system. 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 inter­ +sends only an input event message to. Of course, usually the general inter- pretation is processed by Xlib, Xaw, Motif, Qt, Gtk and similar libraries. The X server only supplies its mapping table (usually upon an application startup). @@ -120,11 +120,11 @@ 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 modi­ +modifiers. key, for instance, usually doesn't depend on any modi- fiers so it its row has only one column defined. Note that in XKB there is no prior assumption that certain modifiers are -bound to certain columns. By editing proper files (see refnam (section 4.2, +bound to certain columns. By editing proper files (see keytypes (section 4.2, page 1)) this mapping can be changed as well. Unlike the original X protocol the XKB approach is far more flexible. It is @@ -132,45 +132,45 @@ 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. +set of symbols (like more than one alphabet) defined in a single mapping ta- +ble. 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. To sum it up: - · for each keycode XKB keyboard map contains up to four one-dimensional + o for each keycode XKB keyboard map contains up to four one-dimensional tables - groups (logically different symbol sets) - · for each group of a keycode XKB keyboard map contains some columns - + o for each group of a keycode XKB keyboard map contains some columns - shift levels (values reached by combinations of Shift, Ctrl, Alt, ... modifiers) - · different keycodes can have different number of groups + o different keycodes can have different number of groups - · different groups of one keycode can have different number of shift lev­ + o different groups of one keycode can have different number of shift lev- els - · the current group number is tracked by X server + o the current group number is tracked by X server -It is clear that if you sanely define levels, groups and sanely bind modi­ +It is clear that if you sanely define levels, groups and sanely bind modi- fiers and associated actions you can have simultaneously loaded up to four different symbol sets where each of them would reside in its own group. The multi-layout concept provides a facility to manipulate xkb groups and -symbol definitions in a way that allows almost arbitrary composition of pre­ +symbol definitions in a way that allows almost arbitrary composition of pre- defined symbol tables. To keep it fully functional you have to: - · define all symbols only in the first group + o define all symbols only in the first group - · (re)define any modifiers with extra care to avoid strange (anisometric) + o (re)define any modifiers with extra care to avoid strange (anisometric) behaviour 4. Defining New Layouts -See Some Words About XKB internals for explanation of used xkb terms and problems addressed by XKB extension. @@ -183,7 +183,7 @@ explanation of syntax of xkb configuration files. If you are about to define some European symbol map extension, you might want to use on of four predefined latin alphabet layouts. -Okay, let's assume you want extend an existing keymap and you want to over­ +Okay, let's assume you want extend an existing keymap and you want to over- ride a few keys. Let's take a simple U.K. keyboard as an example (defined in pc/gb): @@ -221,11 +221,11 @@ altering what may be needed. 4.2 Key Types -The differences in the number of columns (shift levels) are caused by a dif­ -ferent types of keys (see the types definition in section basics). Most key­ -codes have implicitly set the keytype in the included 'pc/latin' file to -'FOUR_LEVEL_ALPHABETIC'. The only exception is keycode which is -explicitly set 'TWO_LEVEL' keytype. +The differences in the number of columns (shift levels) are caused by a dif- +ferent types of keys (see the types definition in section basics). Most key- +codes have implicitly set the keytype in the included "pc/latin" file to +"FOUR_LEVEL_ALPHABETIC". The only exception is keycode which is +explicitly set "TWO_LEVEL" keytype. All those names refer to pre-defined shift level schemes. Usually you can choose a suitable shift level scheme from default types scheme list in proper @@ -239,10 +239,10 @@ The most used schemes are: 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 modi­ + The second level may be chosen by Shift modifier. If Lock modi- fier (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 cap­ + modifier apply the symbol from the second level is taken and cap- italization rules are applied (and usually have no effect). ALPHABETIC @@ -260,7 +260,7 @@ The most used schemes are: 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 modi­ + LevelThree are taken into that consideration. If the Lock modi- fier is active capitalization rules are applied on the resulting symbol. @@ -286,10 +286,10 @@ The most used schemes are: caps variant. FOUR_LEVEL_KEYPAD - Is similar to KEYPAD scheme but considers also LevelThree modi­ + Is similar to KEYPAD scheme but considers also LevelThree modi- fier. 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+Num­ + the symbol from the fourth level is taken. If all Shift+Num- Lock+LevelThree modifiers apply the symbol from the third level is taken. This also, shift-cancels-caps variant. @@ -297,18 +297,18 @@ Besides that, there are several schemes for special purposes: PC_BREAK It is similar to TWO_LEVEL scheme but it considers the Control - modifier rather than Shift. That means, the symbol from the sec­ + modifier rather than Shift. That means, the symbol from the sec- ond level is chosen by Control rather than by Shift. PC_SYSRQ - It is similar to TWO_LEVEL scheme but it considers the Alt modi­ + It is similar to TWO_LEVEL scheme but it considers the Alt modi- fier rather than Shift. That means, the symbol from the second level is chosen by Alt rather than by Shift. 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 modi­ + from the first level is chosen. Only if both Alt+Control modi- fiers apply the symbol from the second level is chosen. SHIFT+ALT @@ -319,27 +319,27 @@ Besides that, there are several schemes for special purposes: If needed, special caps schemes may be used. They redefine the standard behaviour of all *ALPHABETIC types. The layouts (maps of symbols) with keys -defined in respective types then automatically change their behaviour accord­ +defined in respective types then automatically change their behaviour accord- ingly. Possible redefinitions are: - · internal + o internal - · internal_nocancel + o internal_nocancel - · shift + o shift - · shift_nocancel + o shift_nocancel None of these schemes should be used directly. They are defined merely for 'caps:' xkb options (used to globally change the layouts behaviour). -Don't alter any of existing key types. If you need a different behaviour cre­ +Don't alter any of existing key types. If you need a different behaviour cre- ate a new one. 4.2.1 More On Definitions Of Types -When the XKB software deals with a separate type description it gets a com­ -plete list of modifiers that should be taken into account from the 'modi­ +When the XKB software deals with a separate type description it gets a com- +plete list of modifiers that should be taken into account from the 'modi- fiers=' list and expects that a set of 'map[]=' instructions that contain the mapping for each combination of modifiers mentioned in that list. Modifiers that are not @@ -355,7 +355,7 @@ Lets consider an example with two modifiers ModOne and ModTwo: map[ModOne] = Level2; }; -In this case the map statements for ModTwo only and ModOne+ModTwo are omit­ +In this case the map statements for ModTwo only and ModOne+ModTwo are omit- ted. It means that if the ModTwo is active the subroutine can't found explicit mapping for such combination an will use the default level i.e. Level1. @@ -373,7 +373,7 @@ the ModOne state only. That means, ModTwo alone produces the Level1 but the combination ModOne+ModTwo produces the Level2 as well as ModOne alone. 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 combina­ +first case (the Lock itself is included in the list of modifiers but combina- tions 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 @@ -383,7 +383,7 @@ as well as from the second level. Usually, all modifiers introduced in '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 '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 @@ -401,12 +401,12 @@ as seen in for example basic, pc or mousekeys key type definitions. 4.3 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, sym­ +The rules file describes how all the five basic keycodes, types, compat, sym- bols and geometry components should be composed to give a sensible resulting xkb configuration. The main advantage of rules over formerly used keymaps is a possibility to -simply parameterize (once) fixed patterns of configurations and thus to ele­ +simply parameterize (once) fixed patterns of configurations and thus to ele- gantly allow substitutions of various local configurations into predefined templates. @@ -446,7 +446,7 @@ Each rule defines what certain combination of values on the left side of equal sign ('=') results in. For example a (keyboard) model macintosh_old instructs xkb to take definitions of keycodes from file keycodes/macintosh while the rest of models (represented by a wild card '*') instructs it to -take them from file keycodes/xorg. The wild card represents all possible val­ +take them from file keycodes/xorg. The wild card represents all possible val- ues 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. @@ -455,17 +455,17 @@ As you can see some lines contain substitution parameters - the parameters preceded by the percent sign ('%'). The first alphabetical character after the percent sign expands to the value which has been found on the left side. For example +%l%(v) expands into +cz(bksl) if the respective values on the -left side were cz layout in its bksl variant. More, if the layout resp. vari­ +left side were cz layout in its bksl variant. More, if the layout resp. vari- ant parameter is followed by a pair of brackets ('[', ']') it means that xkb -should place the layout resp. variant into specified xkb group. If the brack­ +should place the layout resp. variant into specified xkb group. If the brack- ets are omitted the first group is the default value. So the second block of rules enhances symbol definitions for some particular -keyboard models with extra keys (for internet, multimedia, ...) . Other mod­ -els are left intact. Similarly, the last block overrides some key type defi­ +keyboard models with extra keys (for internet, multimedia, ...) . Other mod- +els are left intact. Similarly, the last block overrides some key type defi- nitions, 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 us layout of macintosh keyboard and standard pc sym­ +symbols for each variant us layout of macintosh keyboard and standard pc sym- bols in appropriate variants as a default. 4.4 Descriptive Files of Rules @@ -477,10 +477,10 @@ know what is your work about. 4.4.1 Old Descriptive Files The formerly used descriptive files were named .lst Its structure is -very simple and quite self descriptive but such simplicity had also some cav­ +very simple and quite self descriptive but such simplicity had also some cav- ities, 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 con­ +compatibility with some older programs, new XML descriptive files can be con- verted to old format '.lst'. For each parameter of rules file should be described its meaning. For the @@ -505,7 +505,5 @@ rules file described above the .lst file could look like: And that should be it. Enjoy creating your own xkb mapping. - $Id$ + Generated from Id: XKB-Enhancing.sgml,v 1.1.10.2 eich Exp $ - -$XFree86$ -- cgit v1.2.3